HookPartly tested (needs an account)

Stop the agent saying done too early

proof-of-green

Free MIT hook that won't let your assistant say it's finished after changing code until a test has passed, or until it tells you plainly why it can't.

Works with
Claude Code, Codex CLI
Good for
Web developers, Everyone

What it does

A common problem with coding assistants is that they say "done" when nothing was tested. proof-of-green is a small check that runs each time the assistant tries to finish its turn.

It looks at the commands the assistant really ran and their real results, not at what it wrote about them. If code changed and no test passed after the change, it sends the assistant back once with a clear message: run the tests, or explain plainly why not.

It blocks only once per finish attempt, so an assistant that truly cannot get tests passing can still stop and tell you. It never runs your tests itself. It is one script with no extra dependencies.

In Claude Code it also checks each sub-agent when that sub-agent stops.

Example prompts

  • "Fix the price rounding bug and make sure the tests pass."
  • "Add a contact form to the site."
  • "This project has no tests, so just make the change and tell me."
  • "Why did you stop before running the tests?"

How to install

claude plugin marketplace add BekirEfeoglu/proof-of-green
claude plugin install proof-of-green@proof-of-green

How to use it

Nothing to type: start a new session and work as usual. If the assistant changed code and no test passed afterwards, it is sent back once to run the tests.

Check it works

Start a new Claude Code session, ask for a small code change and tell the assistant not to run the tests. When it tries to finish, it should get a "proof-of-green:" message and either run the tests or tell you why not. For a full report, npx proof-of-green doctor shows whether the Claude Code plugin and the Codex hooks are installed and trusted (it runs the npm package).

Common problems

Other assistants

What to watch out for

  • Adds five Claude Code hooks (hooks/hooks.json): UserPromptSubmit, PostToolUse (Edit, Write, MultiEdit, NotebookEdit, Bash, PowerShell and every MCP tool), PostToolUseFailure, Stop and SubagentStop. Each one runs node gate.cjs on your computer with a 10-second limit, so every MCP tool call adds a little delay
  • Needs Node.js 18 or newer on your PATH, because the hooks call node
  • Writes a per-session ledger of the commands the assistant ran and their exit codes (deleted after 7 days) and an errors.log in a proof-of-green state folder. With PROOF_OF_GREEN_DEBUG=1 it also writes debug.log with command output and file paths; treat that file as sensitive. No network calls were found in the code
  • It only checks that a test command ran and passed after the last code edit; it cannot judge whether the tests are good. Scripts, node -e, python -c and git commands that change the whole working tree (git pull, git reset --hard) can change code without it seeing the edit, so it is a safety net, not a guarantee
  • Codex route: npx proof-of-green install codex runs the npm package (npm latest is 0.6.0 while the repository is at 0.7.0), copies the gate into Codex's state folder and adds PostToolUse and Stop hooks to ~/.codex/hooks.json. Codex runs new hooks only after you trust them in /hooks (official Codex hooks docs). The README calls Codex hooks experimental; the current Codex docs say hooks are on by default. The gate reads exit codes from Codex's session log, whose format is undocumented

Licence and author

Licence
MIT
Author
Bekir Efeoğlu (BekirEfeoglu)
Source code
github.com/BekirEfeoglu/proof-of-green

How we tested it

We installed it on an empty test computer on 3 Nov 2026. Partly tested: installed in a clean test system, but its main features need an account or key we did not use.

Test level
Technical details of the test
Date
3 Nov 2026
Method
Reviewed by our team against the repository, its README and docs.

Checked again on 3 Nov 2026

Alternatives

  • cc-safety-net — blocks dangerous commands rather than checking tests
  • PR Review Toolkit (Anthropic) — reviews the change after the fact
  • Superpowers — workflows that ask the agent to test, without enforcing it
  • Hookify — write your own hook rules in plain words

FAQ

  • Q: Does it run my tests itself? A: No. It only reads the commands the assistant ran and their exit codes.
  • Q: What if my project has no tests? A: The assistant can say so plainly and finish; the gate blocks only once.
  • Q: How do I remove it? A: claude plugin uninstall proof-of-green@proof-of-green and claude plugin marketplace remove proof-of-green, or npx proof-of-green uninstall codex for Codex.

Sources

  • github.com/BekirEfeoglu/proof-of-green
  • github.com/BekirEfeoglu/proof-of-green/tree/539f28dd668960779c07179f4ba43dfa77de46e7
  • github.com/BekirEfeoglu/proof-of-green/blob/539f28dd668960779c07179f4ba43dfa77de46e7/README.md
  • github.com/BekirEfeoglu/proof-of-green/blob/539f28dd668960779c07179f4ba43dfa77de46e7/hooks/hooks.json
  • github.com/BekirEfeoglu/proof-of-green/blob/539f28dd668960779c07179f4ba43dfa77de46e7/gate.cjs
  • github.com/BekirEfeoglu/proof-of-green/blob/539f28dd668960779c07179f4ba43dfa77de46e7/CHANGELOG.md
  • registry.npmjs.org/proof-of-green
  • learn.chatgpt.com/docs/hooks
  • code.claude.com/docs/en/hooks