# Make your AI check its work

> Run the same small validator with any agent. Includes Codex and Claude hook setup, plus a plain-command fallback.

Page: https://videotomd.com/b/text-starter-working-check/
Tool: Any AI · Tags: portable, free, working-check · 502 words, about 653 tokens
Pills: free · Python · checked 2026-10-09 · Codex · Claude Code · Any AI · file tools · shell · on demand · frontier · coding

## Recipe

- Kind: hook
- Stage: not set
- Loads: on demand
- Works in: Codex, Claude Code, Any AI
- Needs: file tools, shell
- Bring: Python
- Cost: free
- Model: frontier
- Tested in: not yet
- Checked: 2026-10-09
- For: coding

## Put it here

Loads on demand: paste or attach it when the task comes up. To have it every session, put it where your tool reads instructions:

- Codex: Save as AGENTS.md in the repo root. Codex concatenates AGENTS.md from the git root down to the working directory, closer wins. Commit it. Start a new session. Reload: new session. Check it loaded: ask: Summarize the current instructions; `codex status`. Source: https://learn.chatgpt.com/docs/agent-configuration/agents-md (checked 2026-10-12).
- Claude Code: Save as CLAUDE.md in the project root, or .claude/CLAUDE.md. Other agents share the repo: put the shared rules in AGENTS.md and make CLAUDE.md one line, @AGENTS.md. Commit it. Start a new session: the file is read at launch. Reload: new session (or /memory to open the files). Check it loaded: /context lists the Memory files it read; /skills, /agents, /hooks list the rest; the InstructionsLoaded hook event fires once per loaded instruction file. Source: https://code.claude.com/docs/en/memory (checked 2026-10-12).
- Any AI: Coding agent: save as AGENTS.md in the project root (read natively by Codex, Cursor, Copilot, Gemini CLI, Kiro, Devin, Cline, Roo, OpenHands, OpenCode, Goose, Amp, Zed, Warp, Junie, Factory and Jules; Claude Code when no CLAUDE.md exists; Aider with --read). Chat: paste it first. Reload: new session. Check it loaded: ask it to repeat one rule from the file. Source: https://agents.md/ (checked 2026-10-12).

## Access

Free, no signup. The complete file follows.

---

# Make your AI check its work

## Before you start

Use a text-capable AI and Python 3 on your machine or agent host. This example validates a small completion record. It checks structure and declared status; it cannot prove that a model's recorded test actually ran.

Download `check_handoff.py` and `handoff_hook.py` from the companion links on this page. Put both in a `checks` folder in your project. No Python packages are required.

## Steps

1. Ask your AI to complete a small task and write `checks/handoff.json` using the example shape below. Require actual observed checks and list unfinished work.
2. Run `python checks/check_handoff.py checks/handoff.json`. Use `python3` or `py -3` if that is your installed Python launcher.
3. If the exit code is nonzero, fix the work or keep the task incomplete. Do not change a failed check to pass without new evidence.
4. Try the invalid fixtures below before enabling automatic execution.
5. Use the same checker from Codex, Claude Code, a local agent, a human-run terminal or CI. Connect an event hook only in a host that supports it.

```json
{
  "task": "Summarize two supplied notes",
  "result": "summary.md",
  "checks": [{"name": "Compared each claim with its cited source", "status": "pass"}],
  "unresolved": []
}
```

## Codex hook setup

Merge this object into `.codex/hooks.json`. Replace the command with your Python executable and the absolute script path, quoting paths containing spaces. Review and trust the project hook when Codex requests it. This is a post-edit report, not a pre-edit blocker. [Codex hook documentation](https://learn.chatgpt.com/docs/hooks).

```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "^(apply_patch|Edit|Write)$",
      "hooks": [{"type": "command", "command": "python /absolute/project/checks/handoff_hook.py", "timeout": 10}]
    }]
  }
}
```

On Windows, use a command such as `py -3 C:/projects/demo/checks/handoff_hook.py`. In JSON, quotes inside a command string must be escaped. The adapter locates `handoff.json` beside itself, so a different session working directory does not change the file checked.

## Claude Code hook setup

Merge the same `hooks` object into `.claude/settings.json`, replacing the matcher with `^(Edit|Write)$`. Set the same absolute command path and review the script before enabling it. [Claude Code hook documentation](https://code.claude.com/docs/en/hooks).

## Open-weight models and other hosts

The checker is ordinary Python and does not call a model API. Ask your agent to run it after producing the handoff. If the host exposes a post-write callback, connect that callback to the checker and show its result to the agent. Otherwise run the command yourself or in CI. A prompt asking for a check is not an enforced event hook.

For a blocking downstream action, invoke the checker in the script that performs that action and stop on nonzero exit before acting. A post-edit hook cannot undo a write that already happened.

## Completion check

The example must exit zero. Change `status` to `fail`, add an unresolved item, remove `result`, supply invalid JSON, and point at a missing file: each must exit nonzero. Trigger an actual edit in your selected agent and confirm its hook displays the check result. Native hook setup remains unverified until that observation succeeds in your installation.