# Rabbit Brain

> `git status` says what state your code is in; `rb status` says what state your research is in. Rabbit Brain is the record of the ML experiments you run with coding agents: questions, experiments with their hypothesis and variants, criteria declared before the evidence, settings with where each value came from, runs with a receipt and analyses with their intervals, kept as plain YAML files in `.rb/` next to the code. Anyone records, a human or an agent; `rb` checks the sources, computes the findings, and records who made every write. `pip install rabbit-brain`, then `rb docs`.

The user starts it with one line in the agent's chat: "Use Rabbit Brain to track this: read rb context, then record where the work stands." In a project already under way with nothing recorded yet, `rb context` opens with what to do now: record where the work stands, from the files, in that turn and without asking; `rb docs --start` is the start protocol for it.

If a project has a `.rb/` directory, an agent runs `rb context --model <its model id>` before anything else: it is the state of the work, and it replaces any summary of it, and rb keeps the model with the agent's writes in that session. The agent records when the research state materially changes (a question or hypothesis introduced, revised or dropped; an experiment or control proposed or run; evidence that changes a conclusion; a baseline, variant or metric established; an important uncertainty; the next experiment or a decision chosen), not implementation chatter, and cites the repository's own files as sources rather than copying their prose. It writes the record's text as plain text, with Unicode symbols rather than LaTeX, since rb shows text exactly as written. Each criterion names the question its finding bears on (`rb criterion add ... -q <question>`, or `rb criterion file <criterion> <question> --why "..."` for one already recorded): a question's reading counts only the criteria linked to it. `rb reconcile` compiles what the repository's own files already say (each results folder with a report as an experiment, its reports quoted verbatim with file and line, its manifests checked against the code, its audits and checks with their last outcome, its reproduction guide, whether git is clean enough to checkpoint) against the record, and `rb reconcile --apply` keeps it; it is the net under what the agent records, not a substitute. `rb` verifies a setting only by reading its source and finding the value stated there, and computes every criterion's finding from its runs and analyses each time it is read. The agent must not compute findings, regressions or rankings itself.

`rb` is a tracker of what agents and humans do, not a governance tool: it never refuses a write because of who makes it. Every write records who made it (`human:<name>` or `agent:<name>`), the chat session when the runtime exports one, and the reason as given; inside an agent session a human's name in `RB_ACTOR` is ignored, so the record shows who actually did what. Calls on results and on lines of work (accept, reject, investigate; continue, park, stop, pivot, ship) are the user's: an agent records one when the user asks, passing their words verbatim with `--words`, and the call is proposed, not made, changing nothing until the user confirms it in their own terminal (`rb confirm <id>`). rb says words an agent gave as `words (as given): "..."`, never as the user's, until the user confirms the call they came with; then rb's text says them as `your words: "..."`, the user's own screens in quotes without that tag, and a page anyone may be sent never says them. A past call takes `--past`, and it waits for the same one confirmation whatever document it cites; rb says beside it what git shows of that document. No screen names who made a write.

What `rb` cannot do: it does not decide or launch experiments (`rb journal run` only wraps a command it is given), train anything, or certify a model. It cannot make an agent record a choice that only lived in the chat, and it cannot judge whether a method fits the question. It sees only what is in the repository and what runs through `rb journal run`: on its own it looks in `out/`, `outputs/`, `results/`, `eval-out/`, `metrics/`, every folder named for results down to four levels (`reports/stage1/eval/`, `artifacts/`) and any folder a recorded run named, at the files in the repository's top folder, and at .json, .yaml and .toml files git shows as new or changed, and it reads what code, configs, docs and database rows say only where the record points to them. A receipt is what `rb` saw when the run was recorded, not proof of what produced it. What it does: nothing a session wrote reads as the user's until they confirm it, every setting says where its value came from, and every finding is computed from the files, not from the agent's account.

What an agent must pass on to the user, because a summary that drops it is misleading: a finding on its axes exactly as `rb show` prints it (the comparison with its interval and units, the rule, the timing: `estimate meets criterion · point only` on 2 units is not "it works"), every integrity problem, which settings are provisional rather than verified, what `rb status` lists under Needs judgment, and each call it lists under Proposed, not made, with the `rb confirm <id>` the user runs.

## Docs

- [AGENTS.md](https://raw.githubusercontent.com/rabbit-brain/rb/main/AGENTS.md): the complete manual for agents and humans: the rules, the research-state commands, sources and what "verified" means, how a finding is read on its axes, the JSON output, exit codes, every error code with its fix, what to report to the user.
- [README.md](https://raw.githubusercontent.com/rabbit-brain/rb/main/README.md): what it does and what it does not do.
- [CHANGELOG.md](https://raw.githubusercontent.com/rabbit-brain/rb/main/CHANGELOG.md): what each version added.
- [rb-v1.schema.json](https://github.com/rabbit-brain/rb/blob/main/schema/rb-v1.schema.json): the record's format as one JSON Schema (`rb schema all`); every file in `.rb/` opens with `rb: 1` and its `kind`.

## Package

- [PyPI: rabbit-brain](https://pypi.org/project/rabbit-brain/): `pip install rabbit-brain` (the `rb` binary, with pydantic and textual for the Python SDK and the terminal screen). Python 3.10 or later. CLI: `rb`. `rb` never publishes: `rb export` writes the page to host anywhere, and with `--with-record` a bundle carrying the record, which `rb clone` reads; `rb` uploads nothing unless someone runs `rb sync`, which sends the page, and the record only with `--with-record` (optional: a private copy in a rabbitbrain.ai account, made public, if ever, on the site); usage analytics is off unless the user runs `rb telemetry enable`.
- [Source](https://github.com/rabbit-brain/rb): Apache-2.0.
