Your first record

This page starts the record in your repository, hands it to your coding agent, and shows what you read when the agent is done.

Start the record

In your own terminal, in the repository you work in:

rb init "<the work's theme>"

The title names the work’s theme: a paper’s title, a model, a line of work. Each thing the work tries to find out becomes a question of its own later. We ran it in a small repository: a ViT-Tiny training script that trains with and without label smoothing, three configs, a CLAUDE.md, and a plan in docs/plan.md that says “Label smoothing 0.1 is worth keeping if it raises top-1 by at least 0.3 points.”

$ rb init "Label smoothing on ViT-Tiny"
Project 'label-smoothing-on-vit-tiny' started: ~/vit-smoothing/.rb
Rabbit Brain YAML files beside the code: commit .rb/ with it, so the record travels with the work.

For the agents here:
  Claude Code (CLAUDE.md): the skill in .claude/skills/rabbit-brain/SKILL.md; rb's MCP server in a new .mcp.json; rb's session hook in a new .claude/settings.json (SessionStart and Stop run rb journal scan, which looks at the repository and says nothing)

Then paste this line into your agent's chat:
  Use Rabbit Brain to track this: read rb context, then record where the work stands.

rb init creates .rb/ and installs rb’s instructions for the coding agents it finds in the repository: here, Claude Code, because of CLAUDE.md. With them comes a session hook in .claude/settings.json, so rb looks at the repository as each session starts and as each turn ends. Connect your agent says what it installs for Claude Code, Codex and Cursor. A session that is already running loads no skill added during it, so start a new one.

Hand it to your agent

Paste the line rb init printed into your agent’s chat. Add what you want done, in your own words:

Paste this into your agentCopy

Track this with Rabbit Brain, and do one piece of work.

The first sentence is the line rb init prints. Works in Claude Code, Codex, Cursor, or any agent that runs terminal commands.

Use Rabbit Brain to track this: read rb context, then record where the work stands.
Then find out whether label smoothing is worth keeping on our ViT-Tiny, with seeds 1 to 3.

What the agent did

Everything below is rb’s real output from that session. The agent read rb context first. In a repository with work in it and nothing recorded yet, the briefing opens with what to do now:

$ rb context
# The record: Label smoothing on ViT-Tiny

## First, record where the work stands

Nothing is recorded yet, and this project holds work already done: 1 commit. Record where the work stands now, in this turn, from the files, and ask the researcher nothing first. How: rb docs --start.

Generated by `rb context` from `.rb/`; read the state from here or `rb status --json`, never from memory or a summary.
… (49 more lines)

It recorded the question with your words kept beside it, then the experiment, each setting from the file that states it, and the criterion from the plan, cited to its line. All of it came before the first run:

$ rb question add "Is label smoothing worth keeping on our ViT-Tiny?" --id q-smooth --words "find out whether label smoothing is worth keeping on our ViT-Tiny"
q-smooth: Is label smoothing worth keeping on our ViT-Tiny?

Next: rb experiment add "<what would answer it>" -q q-smooth --hypothesis "<what you expect>"

$ rb spec set smooth --from configs/train.yaml --keys "optim.*,data.*"
smooth: 3 settings from configs/train.yaml @234b059 · 3 verified

$ rb criterion add "Label smoothing 0.1 raises top-1 by at least 0.3 points" -e smooth -q q-smooth --metric change.top1 --at-least 0.3 --min-n 3 --why docs/plan.md:3 --id smoothing-helps
smoothing-helps: Label smoothing 0.1 raises top-1 by at least 0.3 points
  change.top1 ≥ 0.3 (n ≥ 3) · primary · on smooth
  declared; no evidence recorded yet

Next: rb run add smooth --from <the results file a run wrote> --set seed=<value>

smoothing-helps is the criterion’s id: its name in every command.

It ran each seed through rb journal run, so the command, its exit code and the files it wrote are kept, and recorded each run from its own output file. After the third seed, the criterion has an interval:

$ rb journal run -- python train.py --seed 3
{"metrics": {"plain.top1": 71.55, "smooth.top1": 72.1}}
exit 0. The command, its exit code and what it wrote are in the journal.
It printed its metrics: plain.top1=71.55, smooth.top1=72.1. rb reconcile proposes the run of smooth that records them.

Since this session last looked:
  - out/seed3/ holds results no recorded experiment reads yet   (rb reconcile)
  - out/seed3/metrics.json: results landed and are not in the record   (rb reconcile)

Next: rb reconcile

$ rb run add smooth --from out/seed3/metrics.json --set seed=3 --config out/seed3/config.yaml --command "python train.py --seed 3" --commit 234b05955a4653f6e045af115202ce98dbdb730b
runvkwdbb on smooth: plain.top1=71.55, smooth.top1=72.1 · seed=3
  Ran with the spec: 4 of its settings found in out/seed3/config.yaml, all matching.
  Only rb's own files are uncommitted (.claude/settings.json, .claude/skills/rabbit-brain/SKILL.md, .mcp.json): they are not the run's code, so the receipt reads the tree as clean.
  Produced: 2026-11-06 20:25:06 (file)
  smoothing-helps criterion met · gain: change.top1: +0.54 [+0.4017, +0.6783] % · paired difference, t interval, 3 seeds, 95% (rb)

Next: rb show smoothing-helps

The files rb init installed are uncommitted, but they are rb’s own, not the run’s code, so the receipt reads the tree as clean.

What you’ll see

Run rb status in your own terminal:

$ rb status
Label smoothing on ViT-Tiny · label-smoothing-on-vit-tiny

Is label smoothing worth keeping on our ViT-Tiny? (open)
  Label smoothing 0.1 raises top-1 by at least 0.3 points. change.top1: +0.54 [+0.4017, +0.6783] % · paired difference, t interval, 3 seeds, 95% (rb); gain: the interval clear of 0 on the better side (higher is better); criterion met: estimate +0.54 ≥ 0.3; rule and question link declared before the evidence (by production times). units: 3 seeds.

Rules: 1 met

The design of 1 experiment is not confirmed: rb confirm lists it.

rb looks in out/, outputs/, results/, eval-out/ and metrics/ at the top, in folders named for results (results/, eval/, metrics/, reports/, artifacts/ and the like), down to 4 levels from the top, at the files in the repository's top folder, and at .json, .yaml and .toml files git shows as new or changed. It last looked at 2026-11-06 20:25 UTC. It reads what code, configs, docs and database rows say only where the record points to them, and it sees only the commands run through rb journal run.

Rules
  smoothing-helps Label smoothing 0.1 raises top-1 by at least 0.3 points
          criterion met · gain · change.top1 ≥ 0.3 (n ≥ 3)
          reads:     change.top1: +0.54 [+0.4017, +0.6783] % · paired difference, t interval, 3 seeds, 95% (rb)
          result:    gain: the interval clear of 0 on the better side (higher is better)
          rule:      criterion met: estimate +0.54 ≥ 0.3
          timing:    declared before the evidence (by production times)
          units:     3 seeds

Experiments
  smooth  Label smoothing 0.1 vs none · open · plain (baseline) vs smooth (candidate) · varies label_smoothing · not frozen · settings 5 verified · 0 provisional · 0 unknown · 1 per-run · runs 3
          to run again: code ok · environment ok · files ok

Runs: 3 recorded on 1 experiment · every receipt is what rb wrote

Nothing open.

Next: rb confirm

Read it top down: the project; the question, with its criterion read under it; the tally; what waits for you; the line that says what rb looks at; then each criterion on its axes, each experiment, and the runs. The criterion was declared before any run, so its timing reads “declared before the evidence”. Findings explains each line.

Make it yours

The agent wrote the experiment’s design: the question it is filed under, its variants, its settings and the criterion. A design an agent wrote reads “not confirmed” until you look at it and confirm it. rb confirm lists it, part by part, and ends with the command that confirms it as listed:

$ rb confirm
Designs waiting for a confirmation (1):
  smooth: Label smoothing 0.1 vs none
    questions: q-smooth
    hypothesis or purpose: not recorded
    why: not recorded
    variants: plain (baseline), smooth (candidate) · varies label_smoothing
    setting optim.lr: 0.001 from configs/train.yaml#optim.lr
    setting optim.weight_decay: 0.05 from configs/train.yaml#optim.weight_decay
    setting data.batch_size: 128 from configs/train.yaml#data.batch_size
    setting seed: per run
    setting plain.label_smoothing: 0.0 from configs/plain.yaml#label_smoothing
    setting smooth.label_smoothing: 0.1 from configs/smooth.yaml#label_smoothing
    criterion smoothing-helps (primary): change.top1 ≥ 0.3 (n ≥ 3) · for q-smooth
    confirm: rb confirm smooth@f6b6812a74bdbdfd0c6b1dbf8c1ebd0de7390051d0b73fbfb11624b7e88dc0d3

$ rb confirm smooth@f6b6812a74bdbdfd0c6b1dbf8c1ebd0de7390051d0b73fbfb11624b7e88dc0d3
smooth's design is confirmed.

Next: rb status

rb confirm runs only in your own terminal. An agent session that runs it is refused.

Connect your agent

What rb installs for Claude Code, Codex and Cursor.

Cookbooks

Eleven tasks for the work you do next.