brakes is an open-source tool, written in Rust and licensed under Apache 2.0, that installs 21 brakes in a GitHub repository for code written by AI agents and then audits that they are still in place. It was released by José Ramón Pérez Agüera, author of the Spanish-language newsletter Gemba, and its premise is blunt: what stops an agent from shipping broken code is not the instructions it reads, but checks that run whether the agent likes it or not and that it cannot edit.
Key points on brakes for GitHub in 30 seconds
- What it does: installs and monitors 21 brakes, from a protected default branch with no admin bypass to held-out tests and mutation testing on the diff.
- Where it works: GitHub only; the full set of local hooks is available for Claude Code, while OpenCode and Codex get partial coverage.
- First step:
brakes doctor .runs a read-only diagnosis and lists what is missing. - Why it matters: the agent can no longer declare a task done while verification is failing.
For sysadmins and platform teams, brakes covers familiar ground: branch protection, rulesets, GitHub Actions workflows, token permissions and CI scanners. What is new is that it organises all of that around an actor that barely existed in repositories until recently, the agent that works with a developer’s account, opens pull requests on its own or picks up issues from the CI itself.
Why a CLAUDE.md file is not enough
In the article that accompanies the release (in Spanish), Pérez Agüera reviews studies published this year. By his account, an ETH Zurich team found across 438 real-world tasks that rules files barely move an agent’s success rate, although they do make it use the tools they name. Other work he cites describes agents reasoning about hidden tests nobody mentioned, passing the tests they can see while failing held-out ones, and, once merged, needing follow-up fixes more often than human-written changes. He is upfront that the samples are small and that almost nothing has been measured on legacy code.
His practical conclusion matches advice he quotes from Anthropic’s best-practices guide for Claude Code: if a line in CLAUDE.md keeps being ignored despite added emphasis, it should be a hook, something the environment runs rather than the model. It is the same line of thinking as other recent ideas for reviewing AI output more reliably, applied to the point where code enters the repository.
The 21 brakes, layer by layer
The README lists them in the same order as the article, each with its own module:
- On GitHub, before merging (1-6): required CI on every pull request; a protected default branch with no administrator bypass; never merge on red, also locally, through a pre-bash guard hook; explicit approval for changes to CI; review by a model from a different family as a required check; and human review when the team has more than one person.
- Tests the agent does not control (7-11): held-out tests in
tests/heldout/with their own job; coverage over changed lines; characterisation tests before touching old code; user-visible tests with Hurl and Playwright; and property-based and mutation testing on the diff, with a minimum score. - In the agent (12-13): a Stop hook that runs the declared verify command when the agent says it is done and sends it back to work if it fails, plus hard prohibitions such as reading secrets or editing the dependency lockfile.
- Security and supply chain (14-18): gitleaks, OSV-Scanner, Semgrep and Trivy in CI; actions and dependencies pinned by hash, with a cooldown for freshly published versions; exceptions with an expiry date; workflows that never run untrusted code with write permissions; and read-only permissions by default in every workflow.
- Oversight (19-21): periodic audits, delivery and CI health figures such as post-merge fixes and cost per change, and unattended agent work going through the same brakes as everything else.
Installation and first commands
Prebuilt binaries exist for Linux x86_64 and aarch64 and for macOS on Apple silicon. The README suggests downloading them with the GitHub CLI, checking SHA256SUMS and the build attestation with gh attestation verify, and installing the binary on your PATH. On any other platform, build it with Rust 1.99 or later:
cargo install --locked --git https://github.com/gemba-app/brakes --tag v0.5.2Code language: JavaScript (javascript)The author recommends starting with the audit, which needs no configuration and writes nothing:
cd your-repo
brakes doctor . # which brakes are missing and how to add them
brakes doctor . --propose # each fix shown as a diff, nothing written
brakes ci init . # writes a CI seed if there is none (once)
brakes install . # shows the plan, file by file
brakes install . --apply # writes the files
brakes apply . --remote # applies repository settings and rulesetsCode language: PHP (php)doctor also accepts --remote, --json and --fleet for checking several repositories, and the tool has an MCP mode so it can be driven by the agent itself. Several design choices aim to keep the tool from becoming a hole of its own: it only writes to repositories on an allowlist stored on the user’s machine, never inside the repository; it fingerprints every file it installs and stops if someone has edited one by hand; it runs nothing from the project during installation; and when it cannot verify something it reports it as unchecked rather than passing it. It also avoids rerunning tests in CI: the project’s own CI runs them once and uploads coverage data, and brakes’ jobs only judge those results, except for held-out tests, mutation testing and user-visible tests.
Cross-model review needs a provider key stored as a repository secret: OPENAI_API_KEY for Codex, the default, CLAUDE_CODE_OAUTH_TOKEN for Claude or DEEPINFRA_API_KEY for DeepSeek. Setting review_family: none turns that brake off.
Limitations to weigh before adopting it
The project is very young, and its author documents the limits. It only supports GitHub, not GitLab or Bitbucket. The full set of local hooks is for Claude Code; OpenCode gets deny rules and Codex relies on server-side required checks. Changed-line coverage and mutation testing are judged only for Rust and Python for now; for Node, Go, Android or iOS the tool says it does not evaluate them. Held-out tests have to be written by the team: brakes sets up the job, the protected folder and the agent prohibition, but nothing is checked until the first test is added. Compared with OpenSSF Scorecard, with which it shares several checks, the README spells out what it borrows, what it covers with zizmor and its own auditor rules, and what it leaves out, such as Fuzzing or CII-Best-Practices.
Frequently asked questions
What does brakes doctor do?
It inspects the repository without changing it and lists the missing brakes, with the module that installs each one or the manual step required. With --propose it shows every fix as a diff.
What are held-out tests in brakes?
Tests the agent can neither read nor edit, stored in tests/heldout/ and run in their own CI job. The team writes them.
Does it work with Codex or OpenCode?
Partly. OpenCode gets deny rules and Codex depends on GitHub’s required checks; the full set of hooks is for Claude Code.
Does it replace OpenSSF Scorecard?
Not entirely. It shares several checks and adds agent-side ones, but leaves out some Scorecard checks such as Fuzzing. Its author recommends keeping Scorecard if you already use it.
Source: José Ramón Pérez Agüera (Gemba) and the gemba-app/brakes repository on GitHub