Your agent says "done". belay makes it prove it.
Give an agent a goal and a command that scores it. The agent works in small steps. A step that improves the score is committed. Any other step is undone. A step that edits the check is refused.
belay is an Agent Skill plus one Python file that
keeps the score. It works in Claude Code, Codex, and any agent that reads
SKILL.md and can run shell commands. It needs git and Python 3.9+ on macOS
or Linux. No packages, no server, no account.
Ask an agent to fix the 12 findings from an audit and it will say "all fixed". Then you find that 3 were fixed by changing what the test expects, one fix broke an unrelated feature, and after its context was compacted it retried ideas it had already ruled out. The agent wasn't lying. It had no score, no memory on disk, and nothing stopping it from grading its own work.
belay takes the grading away from the agent:
belay.py try "cache the parser"
- Refuses to run if a locked file changed (the tests, the benchmark, the fixtures).
- Runs your check and reads the score.
- Runs your guards: the old tests, typecheck, lint. All must pass.
- Better and safe: commits the step, in every repo the climb touches.
- Anything else: resets the tree, in every repo. The idea never lands.
- Writes the step to a log on disk.
The branch only ever holds proven steps, one commit per win.
Claude Code plugin:
/plugin marketplace add Belweave/belay
/plugin install belay@belweave
Any agent, with the skills CLI:
npx skills add Belweave/belayBy hand: copy skills/belay into your agent's skills folder.
git clone https://github.com/Belweave/belay.git
cp -R belay/skills/belay ~/.claude/skills/ # Claude Code
cp -R belay/skills/belay ~/.agents/skills/ # Codex and other agents/belay make the test suite 2x faster
/belay fix every finding from the billing audit, backend and frontend
/belay keep going until every test passes
The plugin's command is /belay:belay. In Codex, type $belay. Or just
ask: "hill climb this until the bundle is under 200 KB".
The agent builds the check, shows you a one-screen plan (the card), and waits for go. Then it climbs on its own and comes back with a report of measured numbers.
If a command can tell you how close you are, you can climb it.
| Goal | The check prints |
|---|---|
| Fix a bug, build a feature | Failing tests written from the spec |
| Audit, "make billing stable" | Failing tests, one per finding |
| Faster | Milliseconds, or better, a count of the work (queries, round trips) |
| Smaller | Bytes of the bundle or the image |
| Port or clone a tool | Outputs that match the real tool, byte for byte |
| UI, copy, API shape | A score from a panel of model judges with your rubric |
Point --score at any test runner's output. No wrapper script needed:
belay.py init billing-audit --goal "every billing finding fixed" \
--check "pytest tests/billing -q" \
--check "cd ../web && npx vitest run billing" \
--score '(\d+) failed' --direction min --target 0 \
--repo ../web --guard "pytest tests/legacy -q" \
--lock tests/billing --lock ../web/src/billing/__tests__Two repos, two suites in parallel, one score.
This is the output of examples/demo.sh, trimmed:
$ belay.py init cart-audit --check "python3 -m unittest discover -s spec" --guard "python3 -m unittest test_old" --lock spec ...
Baseline 4 (min), check takes 0.0s.
$ belay.py try "start the sum at zero"
step 1 kept 3 (was 4, start 4)
$ belay.py try "round every total to whole numbers"
step 2 undone 3 (best 3) <- no gain, tree reset
$ belay.py try "coupon table"
step 3 undone 1 but guard failed: test_old <- fixed 2 bugs, broke an old feature
$ belay.py try "fix the test"
Locked files changed. Undo those edits ... <- tried to edit the test
$ belay.py try "coupon table, VIP kept"
step 4 kept 1 (was 3, start 4)
$ belay.py try "TAKE100, floor at zero"
step 5 kept 0 (was 1, start 4)
BAR REACHED: 0 meets 0. Stop climbing and write the report.
And over a long run:
| Problem | What belay does |
|---|---|
| Context compacted, session crashed | status restores the score, the log, and the notes from disk |
| Noisy benchmark | --runs 3 --paired --min-gain 3% stop a lucky run from counting |
| Overfitting to the test cases | A holdout check the agent never opens |
| Going in circles | PLATEAU after 5 flat steps forces a blocker review. Two reviews with no gain is STUCK |
| "Is it done?" | BAR REACHED: 0 meets 0, not the agent's opinion |
| Command | Does |
|---|---|
init <name> --goal --check --direction min|max |
Baseline, branch, lock |
try "<idea>" [--fix] |
Score the change, keep or undo it |
status |
Score, last steps, notes, PLATEAU or STUCK |
relock --why "..." |
Accept a changed check (a new finding, a better test) |
holdout --why "..." |
Run the hidden cases |
review "<found>" |
Log a blocker review |
raise <bar> --why "..." |
Set a harder bar after reaching this one |
budget, drop, list |
Change limits, start over, list climbs |
init options: --check (repeat), --score '<regex>', --target 0 or
--target 2x, --guard, --lock, --holdout, --repo, --runs,
--paired, --min-gain, --timeout, --max-hours, --max-steps, --here.
The agent's full guide is skills/belay/SKILL.md.
Check recipes are in references/checks.md.
- A climb runs on its own branch,
climb/<name>. Your branch is not touched. - An undo resets the climb branch and deletes untracked files that git does not ignore. If you work in the same checkout at the same time, run the climb in a separate worktree.
- Only one command that changes a climb runs at a time in a checkout.
initandtryrefuse to commit a file over 10 MB.- The lock catches mistakes, not a determined cheat. An agent with a shell can edit anything, so review the branch before you merge it.
- Locks hash file names but not the content of files git ignores, so caches
don't trip them. Don't lock data that git ignores. Put it under
.belay/<name>/, where content is always hashed. - Climb only repos you trust. The check and the guards are shell commands.
- Nothing is sent anywhere. All state is in
.belay/inside the repo.judge.pycalls a model CLI only if you use model judges, and a model judge can be fooled, so prefer an exact check when one exists.
git clone https://github.com/Belweave/belay.git && bash belay/examples/demo.shIt builds a tiny shop in a temp folder, runs a full climb, and deletes it.
python3 tests/test_belay.pyThe tests run real git repos in temp folders. See AGENTS.md.
MIT