Get started
Babbit documentation
Babbit builds and runs software you don't have to read. You approve what the product should do, one scenario at a time. Agents write the code as boxes with contracts and prove each scenario with a test at the commit that ships. When something breaks, Babbit names the box.
What you check instead of code
Most AI coding tools end with a diff for someone to review. Babbit ends with two checks you can run without opening a file.
| Check | What it answers | How |
|---|---|---|
| A run | Where did it break? | Every call that crosses a box's edge is checked against the box's contract. When a run fails, Babbit blames the deepest box that broke its contract while every box it called held. |
| A scenario | Does the product do what was approved? | Each line of the spec maps to a test. For a new or edited line, the test must fail at the base commit and pass at the pull request head. The result is bound to that line and that commit, and editing either voids it. |
Neither check covers the other. Every box can keep its contract while the product does the wrong thing, which means a scenario is missing. A box can break its contract on a path no scenario tests, and only the trace shows it. Babbit runs both.
What Babbit doesn't do
These are rules, not defaults. One owner switch, Land directly, bends the first rule, and what it lands shows as unverified.
- No done without evidence. Nothing shows as done without a test result, screenshot, build or URL bound to a commit. Anything Babbit couldn't verify is listed as not verified, never folded into done.
- No agent writes around the MCP. Babbit's agents and the ones you bring, such as Claude Code or Codex, change the spec, run tests, record evidence and use secrets only through the Babbit MCP. Every call, allowed or refused, is logged.
- No secret values in agent workspaces. A workspace holds handles. Babbit swaps a handle for its value for one call, on a host the secret names. The one exception is the model credential a Claude Code or Codex session needs.
- No grading its own work. The session that wrote the code never records its own evidence or promotes its own change.
- No schedules. A change moves only when an event allows it, such as an approval or a failed test. Nothing runs because a clock says so.
What you do
You approve the lines a change proposes, and you confirm the release. Agents and Babbit do the rest, from the code and tests to merges, deploys and rollbacks. How Babbit works follows one change through all five steps.
Know before you start
- Existing code starts as legacy. When you connect a repository, Babbit reads it into a spec, but box-level traces cover only the code that changes write or rewrite. See Legacy code.
- Production keeps a sample. In prod, every crossing is checked, but only crossings that broke a contract, and one in a hundred of the rest, keep their values. See What a trace keeps.
- A scenario needs a test. A scenario with no mapped test is unverified, and it counts against the change until it has one.
- Babbit is in alpha. These docs describe what the deployed product does today. A designed feature that isn't served yet is marked Planned where it comes up, and What's planned lists them all. If a page and the product disagree, the page is wrong.
How the docs are organized
| Section | What it holds |
|---|---|
| Get started | The box, the whole loop on one page, and the quickstart. |
| Concepts | What each part of Babbit is and the rules it keeps. |
| Guides | One task each, step by step. |
| Reference | Exact lists: MCP tools, states, permissions, branch names and terms. |
Press / to search. Every term has an entry in the glossary.