checkup-cli

A lazy-senior-engineer ruleset for AI coding agents, distributed as an npm package. It installs itself into six agent hosts. Zero runtime dependencies — the tool obeys its own rule 2 (stdlib first) and only uses Node's built-in fs/path/crypto.

Use it without installing anything

npx checkup-cli init

Run this from your project root. It installs every supported host by default.

Or install it

npm install -g checkup-cli
checkup init

Usage

checkup init [--target <names>] [--dir <path>] [--force] [--dry-run]
checkup uninstall [--target <names>] [--dir <path>] [--dry-run]
checkup help
checkup --version

• --target — comma-separated list of hosts, or all (default: all). One of: gemini, trae, claude, cursor, copilot, windsurf.
• --dir — project root to act on (default: current directory)
• --force — overwrite an installed file even if it was hand-edited since the last checkup init (see Overwrite safety below)
• --dry-run — print what would change without touching the filesystem

What it installs

| Host | Path | Notes | |---|---|---| | Antigravity / Gemini CLI | .gemini/extensions/checkup/ | CHECKUP.md, extension manifest, /checkup:review and /checkup:ultra commands. Restart the CLI session after installing. | | Trae | .trae/rules/checkup.md | Trae loads every file under .trae/rules/ — merges in cleanly. | | Claude Code | .claude/rules/checkup.md | Loaded alongside CLAUDE.md — your existing CLAUDE.md is never touched. | | Cursor | .cursor/rules/checkup.mdc | .mdc with YAML front matter (alwaysApply: true). | | GitHub Copilot | .github/instructions/checkup.instructions.md | Scoped instructions file (applyTo: "**") — doesn't touch a repo-wide .github/copilot-instructions.md you may already have. | | Windsurf | .windsurf/rules/checkup.md and .devin/rules/checkup.md | Written to both paths to cover the Windsurf → Devin Desktop rebrand. |

The plain-markdown ruleset body lives in one place (templates/rules.md) and is reused as-is for Trae/Claude Code/Windsurf, and wrapped with front matter for Cursor/Copilot — the prose isn't duplicated per host.

Overwrite safety

checkup init records a checksum of every file it writes in a .checkup-state.json file at your project root. On the next run:

• If an installed file is unchanged since the last install, it's updated silently to the latest version.
• If you (or something else) hand-edited an installed file since the last install, checkup init skips it and tells you, instead of silently overwriting your edit. Pass --force to overwrite it anyway.

Commit .checkup-state.json alongside the installed rule files so teammates get the same protection; it's small, plain JSON, and safe to version-control.

Uninstalling

checkup uninstall [--target <names>] [--dir <path>]

Removes exactly what checkup init installed for the given target(s) (or all of them), and clears their entry from .checkup-state.json.

The ruleset

Before writing code, stop at the first rung that holds:

1. Does this need to exist at all? → skip it (YAGNI)
2. Does the standard library already do it? → use it
3. Is there a native platform feature? → use it
4. Is it already covered by an installed dependency? → use it
5. Can it be one line? → write one line
6. Only then: write the minimum code that works

Never simplified away: trust-boundary validation, data-loss handling, security, accessibility.

Tests

Covers every command path: help/version output, init/uninstall for each target (including the comma-separated multi-target form), --dir handling (including a missing directory), unknown-command/unknown-target errors, content correctness (installed files match the bundled templates, front matter is well-formed, the gemini manifest is valid JSON), idempotency, --dry-run (no filesystem changes), and the overwrite-safety skip/--force behavior. Uses Node's built-in test runner — no test framework dependency.

npm test

CI runs this on every push and pull request across Node 18/20/22 (.github/workflows/test.yml).

Publishing this package yourself

npm login
npm publish

License

MIT — see LICENSE.