ratchet-cliv0.1.0 · MIT

A coding agent gets the next task only after the validators pass.

ratchet-cli is a small command-line tool. You register the work as separate items. It hands them out one at a time, and an item locks only when your own checks, such as lint, tests and the build, exit with 0. There is no “I think it’s done” path.

source on GitHubPython 3.10+standard library only

$ pipx install git+https://github.com/pantagram1031/ratchet-cli

why

Language models write well but can’t reliably tell when the work is finished. So that call is taken away from them and given to programs that give the same answer every time: the tests and checks you already trust.

try it

Pick what each validator returns, then submit. This follows the exit-code rules in the README. It is a simulation, not the CLI’s real output.

[1] implement /login
[2] implement /logout
[3] rewrite User model to use Pydantic v2
DONE

lint.sh

test.sh

warning_blocks allow_skipped

exit codes

What each exit code means, and whether it blocks the submit.

code	meaning	blocks submit?
`0`	pass, actually verified	no
`1`	fail	yes
`2`	warning, counted as advisory	only if `warning_blocks=true`
`78`	skipped: could not verify, e.g. a tool is missing	yes, unless `allow_skipped=true`
`other`	error: the validator itself is broken	yes

A validator that exits 0 without actually checking anything is a false ratchet. Exit 78 is how it says “I couldn’t verify this.”

five-second tour

$ cd my-existing-project
$ ratchet init                # creates .ratchet/, does not touch your code
$ ratchet add "implement /login"
$ ratchet add "implement /logout"
$ ratchet next                # → [1] implement /login
# do the work…
$ ratchet submit              # runs all validators; locks the item if they pass
$ ratchet status              # counts and recent outcomes

The next item is not handed out until the previous one passes. Running ratchet next again before submit returns the same item, so a crash in the middle is safe.

what it writes

Everything lives in .ratchet/ inside your project.

.ratchet/
├── state.json      # items, cursor, current (gitignored, per developer)
├── config.json     # warning_blocks, allow_skipped, …
├── history.jsonl   # append-only log (committed, a team asset)
└── validators/     # your checks: lint.sh, test.sh, … (committed)

with Claude Code

$ ratchet skill > .claude/skills/ratchet/SKILL.md

The bundled skill file teaches the contract: ask ratchet next, do exactly one item, run ratchet submit, read the validator output when it fails, and never declare the work done yourself.

where it comes from

The idea comes from Park Jun-woo’s essays Reins Engineering and The Ratchet Pattern. ratchet-cli is a small CLI we wrote on top of that idea.