# Rabbit Brain

> Rabbit Brain (`rb`) is the record of the ML experiments you run with coding agents, kept as plain YAML files in `.rb/` next to the code: 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. Anyone records, a human or an agent; `rb` checks the sources, computes every finding from the runs each time it is read, and records who made each write. `git status` says what state your code is in; `rb status` says what state your research is in.

## When to use rb

Use rb when a coding agent runs, reads or reports ML experiments in a repository and the user needs to know what was tested, what it showed, and what still needs them. If the project has a `.rb/` directory, it is already in use: read it before anything else. In a project already under way with nothing recorded, record where the work stands from the repository's own files. rb sits beside a tracker such as W&B or MLflow: they keep curves and checkpoints, rb keeps what the numbers were meant to test and whether they do.

## Start here

- [Docs](https://rabbitbrain.ai/docs/): install, a first record, connecting your agent, the concepts, cookbooks, and the CLI reference.
- [AGENTS.md](https://raw.githubusercontent.com/rabbit-brain/rb/main/AGENTS.md): the complete manual, also `rb docs`: the rules, every command, what "verified" means, how a finding is read, the JSON output, exit codes, every error code with its fix. `rb docs --start` prints the start protocol, for recording work already done.
- [auth.md](https://rabbitbrain.ai/auth.md): connecting rb to a rabbitbrain.ai account, with the user's consent.
- [Real records](https://rabbitbrain.ai/demo): two studies an agent kept with rb, in a sample account, read-only. Each page has "Rerun this research": a prompt for a coding agent that clones the record with `rb clone`. The math study's bundle names its code, so the clone checks it out and the study can be rerun; the INT8 study's code is not published, so its clone is the record only.
- [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.
- [Source](https://github.com/rabbit-brain/rb): Apache-2.0.

## Install

```sh
pip install rabbit-brain        # or: uv tool install rabbit-brain, or pipx install rabbit-brain
rb init "<the work's theme>"    # starts .rb/ here; rb init --dry-run lists every file it would write
```

Python 3.10 or later, on Linux, macOS or Windows ([preview](https://github.com/rabbit-brain/rb/issues/2)). The CLI is `rb`. To try it without installing anything: `uvx --from rabbit-brain rb tour`. `rb tour` builds a small project and runs the whole loop; `rb remove` takes out only what is rb's. The user may start it with one line in your chat: "Use Rabbit Brain to track this: read rb context, then record where the work stands."

## The rules an agent follows

- If `.rb/` exists, run `rb context --model <your model id>` before anything else. It is the state of the work and replaces any summary of it, your own included; rb keeps the model with your writes in the session.
- Record when the research state 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 chosen. Not implementation chatter.
- Cite the repository's own files as sources rather than copying their prose. `rb reconcile` compiles what the files already say against the record, and `rb reconcile --apply` keeps it. It names each results file in the top folder: a table (`results.tsv`, `results.csv`, `results.jsonl` and the like) with the `--where` line that reads a row, and a report in prose (`RESULTS.md`, `report.md`), from which rb reads no run. `rb run add <exp> --from <table> --where ... --every-row` records every row `--where` picks, each as its own run.
- Run new experiments through `rb journal run -- <command>`. Each criterion names the question it bears on (`rb criterion add ... -q <question>`, or `rb criterion file <criterion> <question> --why "..."`).
- Never compute findings, regressions or rankings yourself. rb verifies a setting only by finding its value in the source it cites, and computes every finding from the runs and analyses. Read it with `rb show <id>`.
- Write plain text, with Unicode symbols rather than LaTeX: rb shows text exactly as written. Never edit `.rb/` by hand.
- Calls on results and lines of work (accept, reject, investigate; continue, park, stop, pivot, ship) are the user's. Record one only when they ask, with their words verbatim in `--words`. It is proposed, not made, until they run `rb confirm <id>` in their own terminal. A call made before the record began takes `--past`.
- Every write records who made it (`human:<name>` or `agent:<name>`), the chat session and the reason. rb never refuses a write because of who makes it. Do not set or unset `RB_ACTOR`.
- Report to the user: each finding 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 under Proposed, not made, with its `rb confirm <id>`.
- rb does not run, train or certify anything, and cannot judge whether a method fits the question. It sees the repository and what runs through `rb journal run`: `out/`, `outputs/`, `results/`, `eval-out/`, `metrics/`, every folder named for results (`eval/`, `reports/`, `artifacts/` and the like) down to four levels, any folder a recorded run named, the top folder's files, and the .json, .yaml and .toml files git shows as new or changed. A receipt is what rb saw when the run was recorded, not proof of what produced it.
- Every command takes `--json` and prints one JSON object (`ok`, `data`, `errors`, `next`). Exit 0 ok, 1 a check ran and failed, 2 rb could not do what was asked, 3 a fault in rb. When one fails, read `errors[].fix`.
- rb never publishes. `rb page` writes the record's page as one file, `rb export --with-record` a bundle that `rb clone` reads. Nothing is uploaded unless someone runs `rb sync`, and usage analytics is off unless the user runs `rb telemetry enable`.
- Anyone can make an account at https://rabbitbrain.ai/signin. `rb login` signs a machine in to it (the user approves its code), and `rb sync` keeps a private copy of the record's page there. The record needs no account.

## Machine endpoints

- record format (JSON Schema, also `rb schema all`): https://rabbitbrain.ai/schema/rb-v2.schema.json
- agent index: https://rabbitbrain.ai/llms.txt
- hosted account sign-in for agents: https://rabbitbrain.ai/auth.md
- docs: https://rabbitbrain.ai/docs/ (every command: https://rabbitbrain.ai/docs/reference/cli/)

## Support

- [Issues](https://github.com/rabbit-brain/rb/issues)
- [Security reports](https://github.com/rabbit-brain/rb/security/advisories/new), privately.
- [PRIVACY.md](https://github.com/rabbit-brain/rb/blob/main/PRIVACY.md): the opt-in usage analytics, field by field.
- `rb feedback`: a link to send feedback; the page shows what it would send before anything is sent.
- [PyPI: rabbit-brain](https://pypi.org/project/rabbit-brain/)