gatebound
for Claude Code & Codex · MIT

Done only when the gates pass.

Rules in a CLAUDE.md are suggestions. gatebound turns them into hooks: no code before an approved spec, and no “done” until real commands pass.

Standard-library Python, nothing to pip install · Star on GitHub

Prose is a suggestion. A hook is a rule.

An instruction in a prompt is only as reliable as the model's attention in that turn. gatebound moves the parts that matter into gates the host runs on every tool call and at every turn end.

Instructions the model can skip

"Write tests first." "Get approval before touching src/." "Don't say done until it works." Under pressure, any of these can quietly not happen.

# CLAUDE.md
- write the spec before code
- run the tests before saying done

Gates the host enforces

A write to src/ before the spec is approved is denied. A turn that claims done runs the contract first. A check that couldn't run says so.

PreToolUse · write gate
  gatebound: writing code is blocked until
  spec/05-gate.md is approved
Stop · stop gate
  gatebound: the completion contract is not met,
  so this work is not done

Watch a gate fire

An agent asked to build a login page in Claude Code. The red lines are the plugin's actual messages; the file names, criterion id and hash come from an example project.

claude — ~/login-demo
› add a login page ● Write(src/login.tsx) ✗ denied (PreToolUse · write gate) gatebound: writing code is blocked until spec/05-gate.md is approved (current status: unverified). Run the /gatebound:gate pipeline and have the user approve the gate, or write to spec/, docs/ or *.md first. Blocked path: src/login.tsx ● There is no approved spec yet, so I'll write the spec first. /gatebound:interview → /gatebound:tasks → /gatebound:gate › /gatebound:gate (you read the criteria and approve) ● Bash(gatebound approve spec/05-gate.md) approved spec/05-gate.md 3f9a1c0b7e2d › /gatebound:build ● Write(src/login.tsx) ✓ ● Write(tests/login.spec.ts) ✓ ● The login page is done. ✗ blocked (Stop · stop gate) gatebound: the completion contract is not met, so this work is not done (1 of 3 criteria failing or unverified): - login-e2e: fail (exit 1) Fix the causes and let the contract run again. 'unverified' means it was never checked — that is not a pass. ● The e2e test fails on an empty password. Fixing the validation. ● Edit(src/login.tsx) ✓ ● Bash(gatebound contract run) ok ● All 3 criteria pass. Next, /gatebound:verify runs an independent check.

Hook messages follow your language: write in Korean and the same gates answer in Korean. gatebound approve and gatebound contract run are shorthand for the plugin's CLI (python3 …/bin/gatebound.py), which the commands run for you.

From one sentence to a verified change

Every stage writes plain Markdown and JSON under spec/, meant to be reviewed and committed. The build only opens once the gate is approved, and the agent that built something never signs off on it.

discoverFind a problem worth building, no fixed question slots.
interviewPRD and architecture, with live research on the product category.
mockup · designScreens and tokens from Figma, a URL, screenshots or HTML.
tasksVertical slices with non-overlapping write scopes.
gateExecutable criteria you approve; the hash is pinned.
build → verifyGates judge each task, then an independent evaluator checks.

What the gates give you

Small, mechanical guarantees that add up to a build you can trust.

Hash-anchored approvals

Approving a spec records its SHA-256. Edit the file afterward and the approval is stale. Nobody has to remember to re-review.

Executable "done"

Completion is a list of commands that exit 0 and produce the expected artifacts, or they don't. No done on the honor system.

Assumption ledger

Every guess made on your behalf is written down, so nothing gets decided silently.

Four-state verdicts

A check that couldn't run is never rounded to a pass.

okwarnfailunverified

Producer ≠ evaluator

Verification runs in a separate, read-only agent, optionally the other CLI, so a model doesn't grade its own work.

Fails open, never hangs

A broken gate script degrades to "allow and log." Standard-library Python only, no pip install.

Quickstart

From install to a verified change in four steps. Hooks stand down in any project you haven't set up, so nothing changes until you run a command there.

1

Install

# in a terminal $ curl -fsSL https://claude.ai/install.sh | bash $ claude plugin marketplace add gatebound/gatebound $ claude plugin install gatebound@gatebound

The first line installs Claude Code itself; skip it if claude --version already works. You also need git and Python 3.9+: on macOS, xcode-select --install installs both. Open a new terminal afterwards; the Claude desktop app picks the plugin up too.

Step-by-step macOS · Linux guide

Using Codex?
# in a terminal $ codex plugin marketplace add gatebound/gatebound $ codex plugin add gatebound@gatebound

Codex runs a plugin's hooks only after you trust them, so no gate runs until you do this once: run codex (codex --no-daemon if it stops with os error 5), type /hooks, press t on each gatebound hook, then start a new session. Codex 0.167 and later ask at startup instead (“Hooks need review”): choose Trust all and continue. Repeat after every update. The Codex app shares this trust but cannot record it yet, so do it in a terminal.

Check it worked

Open a terminal, move into your project folder (cd my-project), run claude and log in, then type /gatebound:doctor at its prompt (in Codex, $gatebound-doctor). Rows 1 and 2 should read ok; the rest stay unverified until you start a spec. Prefer typing inside Claude Code? /plugin marketplace add https://github.com/gatebound/gatebound, then /plugin install gatebound@gatebound does the same.

  1. 2

    Write the spec

    Open your own project and start with /gatebound:discover if you're still deciding what to build, or /gatebound:interview if you already know. You get spec/01-prd.md and spec/03-architecture.md, with every assumption made for you listed in a ledger.

  2. 3

    Approve the gate

    Run /gatebound:tasks, then /gatebound:gate. Read the completion criteria and approve them. The approval pins the file's hash: from here source files can be written, and editing the gate later expires the approval.

  3. 4

    Build, then verify

    Run /gatebound:build. Each task is judged by its gates, and a turn that claims done runs the contract first. Finish with /gatebound:verify, where a separate read-only agent checks the result.

In Codex the same commands are skills: $gatebound-discover, $gatebound-gate and so on. If something looks off, /gatebound:doctor checks the install and prints a fix for anything that isn't ok.

Claude Code or CodexClaude Code on a paid plan, or the Codex app or CLI.
Python 3.9+ and gitInstalled by you (macOS: xcode-select --install; Windows: the installer above). Reachable as python3, python or py -3. Nothing to pip install.
macOS · Linux · WindowsWindows has a one-line installer and is in preview; WSL behaves like Linux.

FAQ

How is this different from rules in CLAUDE.md or a prompt?

A rule in CLAUDE.md is advice the model may or may not follow in a given turn. gatebound turns the rules that matter into hooks the host runs on every tool call and at every turn end. A write before the spec is approved is denied, and a turn that claims done runs the completion contract first. The model doesn't have to remember anything for the rule to hold.

Does it slow the agent down?

Most gates are a quick check of a file path or a hash. The heavier part is the completion contract, which runs only during a build, at the end of a turn. It starts criteria for up to 120 seconds by default (stop.budget_s); the rest run at the next turn end. When no file changed since the last run, the previous result is reused instead of running again.

Will it change projects where I don't use it?

No. The plugin installs globally, but its hooks stand down in any project that has neither a .gatebound/ directory nor gatebound's spec files: no gate acts and nothing is written. A project opts in the first time you run one of its commands there.

Can the agent just edit the gate or its approval?

Editing spec/05-gate.md after approval expires the approval, so the build stops until you approve again. The approval records and the derived contract under .gatebound/ are written only by gatebound's own hooks and CLI; a direct edit by the agent is denied. A worker session can never approve anything.

What happens if a gate itself breaks?

It fails open. A gate that hits an internal error allows the action and writes a one-line diagnostic to .gatebound/runs/hook-errors.log, so a bug in gatebound never hangs your session. /gatebound:doctor checks the install and prints a fix for anything that isn't ok.

Does it send my code anywhere?

gatebound makes no network requests of its own. It is standard-library Python with nothing to pip install, and it never holds an API key. The only connection it opens is a doctor check for a local dev server on 127.0.0.1. The commands in your contract, and the claude or codex CLI if you use one as a worker, run exactly as you configure them.

Does it work in Codex and on Windows?

Codex installs the same plugin from the same marketplace, and the write, shell, stop and prompt gates run there too. Codex asks you to trust the hooks once (run codex, then /hooks). Windows support is in preview: CI runs on Windows, and Claude Code runs the hooks through Git for Windows. WSL behaves like Linux.

Coming from gatekit?

gatebound 0.17.0 continues gatekit 0.16.15 under its own name, and it reads projects gatekit set up. Swap the plugin and keep working; the steps are in Coming from gatekit. gatekit 0.16.x stays available for the current study cohort at github.com/loganmakes/gatekit.