Skip to content
BelweavePublic

About

Your agent says done. belay makes it prove it: small steps toward a scored goal, wins committed, losses undone, the check locked. An Agent Skill for Claude Code, Codex, and any agent.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

belay

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.

Why

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"
  1. Refuses to run if a locked file changed (the tests, the benchmark, the fixtures).
  2. Runs your check and reads the score.
  3. Runs your guards: the old tests, typecheck, lint. All must pass.
  4. Better and safe: commits the step, in every repo the climb touches.
  5. Anything else: resets the tree, in every repo. The idea never lands.
  6. Writes the step to a log on disk.

The branch only ever holds proven steps, one commit per win.

Install

Claude Code plugin:

/plugin marketplace add Belweave/belay
/plugin install belay@belweave

Any agent, with the skills CLI:

npx skills add Belweave/belay

By 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

Use

/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.

Any goal is a number

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.

What it catches

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

Commands

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.

Safety

  • 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.
  • init and try refuse 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.py calls a model CLI only if you use model judges, and a model judge can be fooled, so prefer an exact check when one exists.

Try it

git clone https://github.com/Belweave/belay.git && bash belay/examples/demo.sh

It builds a tiny shop in a temp folder, runs a full climb, and deletes it.

Development

python3 tests/test_belay.py

The tests run real git repos in temp folders. See AGENTS.md.

License

MIT

About

Your agent says done. belay makes it prove it: small steps toward a scored goal, wins committed, losses undone, the check locked. An Agent Skill for Claude Code, Codex, and any agent.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages