Skip to main content

Rabbit Brain

Know where your research stands. Your AI agent records what was tried, what the results show, and what's still open, with the code and settings.

rb open's first screen on the sample project INT8 ResNet-20 on CIFAR-10: its question, a count of its rules (4 passed, 1 failed, 4 can't tell yet, 4 no results yet), a chart of each rule's result and range, what the results rest on, and the decisions waiting

Quick start: a sample study

Try Rabbit Brain on a sample study, so you don't need to set up any experiments or use your own research. Just open Claude Code or Codex in an empty folder and paste the prompt below.

Clone https://github.com/rabbit-brain/think-step-by-step and work inside it.
Install rabbit-brain from PyPI into a virtual environment in that folder.
It's open source: https://github.com/rabbit-brain/rb
Start rb login in the background and show me the sign-in link it prints. I'll sign in.
When I'm signed in, run rb sync and give me the link it prints.
Run rb context and tell me in three lines what the study found and what's still open.
Don't run any experiments.

Your agent gives you a sign-in link (an email code, no password). Then the study opens in your private account on rabbitbrain.ai. No account? Ask your agent to run rb page instead.

Use it on your own project

Open Claude Code or Codex in your project and paste this prompt. Then run rb open in your own terminal to see the record.

Use Rabbit Brain to keep track of the research in this repository. Record where the work stands now, from its own files.

Set up:
- If `rb --version` fails, install it with `uv tool install rabbit-brain` (or `pipx install rabbit-brain`).
- If this repository has no `.rb/` yet, run `rb init "<the work's theme>"`, then add the question the work is trying to answer with `rb question add`.
- Run `rb docs --start` and follow it. Run `rb context --model <your model id>` before anything else.

Record from the repository's own files, and cite them: the questions, the experiments with each setting and where its value came from, the rules a result must meet, and the runs. Run new experiments through `rb journal run`. Never compute findings, rankings or regressions yourself: rb computes them. Calls on results are mine. Record one only when I ask, in my words, and give me the `rb confirm` command.

If I want a page to share, run `rb page`: it writes the record's page as one file. If I want it in my rabbitbrain.ai account, run `rb login` (I approve its code myself) and then `rb sync`.

Finish with `rb status` exactly as printed, what you recorded, what rb says needs me, and where the page is if you wrote one.

What rb shows you

rb works out each rule's result from the run files every time you ask. Here is rb show <id> --long on the INT8 example further down:

Criterion cviuxxm on int8 (primary, own): INT8 adds at most 0.05 validation loss
  cviuxxm INT8 adds at most 0.05 validation loss
          criterion met · loss · change.val_loss ≤ 0.05 (n ≥ 3)
          reads:     change.val_loss: +0.02667 [+0.01232, +0.04101] nats · paired difference, t interval, 3 seeds, 95% (rb)
          result:    loss: the interval clear of 0 on the worse side (lower is better)
          rule:      criterion met: estimate +0.02667 ≤ 0.05
          timing:    declared after the evidence existed: 1 of 3 units was produced before it was declared; produced after it: +0.025 nats · paired difference, 2 seeds (rb)
          units:     3 seeds
          integrity: ok
  Evidence: 3 runs, each with its files unchanged and its code kept when it was recorded, after the run. rb has not rerun them.
  produced after it was declared: +0.025 nats · paired difference, 2 seeds (rb)
  runso7fgx: difference +0.03 (file) · unit seed=1 · produced before the declaration · seed=1
  runtubqyq: difference +0.02 (file) · unit seed=2 · seed=2
  run2ysivj: difference +0.03 (file) · unit seed=3 · seed=3

The rule allows 0.05 more validation loss. Over 3 seeds INT8 adds 0.027, so the rule is met. Seed 1 existed before the rule was written, and rb says so on every reading.

How it works

  1. Your agent writes to the record as it works. It runs experiments through rb journal run, sets pass marks with rb criterion add and leaves notes with rb note add.
  2. rb checks the record against your repository: each setting against its config file, each result against its output file, each run against its git commit. It never edits your code.
  3. The next session starts from the record. rb context gives a new agent the questions, the results and what is still open.
  4. You make the final decisions. If your agent accepts or rejects a result, it waits until you run rb confirm.

The same work typed by hand, in a repository with its configs in configs/ and each seed's results in out/seed<N>/:

rb init "INT8 ResNet-50"                                               # titled for the work's theme
rb question add "Is INT8 ResNet-50 as good as FP32 on ImageNet?" --id q-imagenet
rb experiment add "INT8 vs FP32" --id int8 -q q-imagenet --hypothesis "INT8 keeps validation loss within 0.05 of FP32" --baseline fp32 --candidate int8 --varies precision
rb spec set int8 --from configs/train.yaml --keys "optim.*,data.*"     # each setting read by key and checked against the file
rb spec set int8 fp32.precision fp32 --source configs/fp32.yaml#precision
rb spec set int8 int8.precision int8 --source configs/int8.yaml#precision
rb spec set int8 seed --per-run                                         # each run gives its own
rb metric add val_loss --unit nats --minimize
rb criterion add "INT8 adds at most 0.05 validation loss" -e int8 -q q-imagenet --metric change.val_loss --at-most 0.05 --min-n 3 --when-met "INT8 stays within the declared accuracy budget on ImageNet."
rb freeze int8 -m "before the held-out runs"                            # locks the rule, recorded with who froze it and why
rb run add int8 --from out/seed1/metrics.json --set seed=1 --config out/seed1/config.yaml
rb status                                                                # where the work stands, and what waits on you
rb context                                                               # what a fresh agent session reads instead of a summary

The record doesn't take the agent's word

  • Settings are checked against your files. A value rb can't find where it is cited shows as provisional.
  • Results are worked out from the runs each time you read them. None is stored.
  • A pass mark written after its results says so on every reading.
  • Every decision keeps who made it and why.

What it doesn't do

  • It doesn't choose or launch your experiments. rb journal run only wraps a command you give it.
  • It doesn't train or certify models.
  • It can't record a choice that only lived in the chat.
  • It sees only your repository and what runs through rb journal run.

Install by hand

pip install rabbit-brain          # or: uv tool install rabbit-brain
uvx --from rabbit-brain rb tour   # a guided example, nothing installed

Python 3.10 or later, on Linux and macOS, and Windows as a preview.

More

  • Docs: every command, the record's files, sharing a record, connecting your agent.
  • Usage analytics are off until you run rb telemetry enable. See PRIVACY.md.
  • Planned: rb paper, a paper's rules and settings as a ready-made experiment.
  • CHANGELOG.md · CONTRIBUTING.md, with building from source.

License: Apache-2.0

Metadata

Release files for rabbit-brain 0.8.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rabbit-brain 0.8.6
File Size Uploaded Provenance Actions
rabbit_brain-0.8.6.tar.gz 4.0 MB Without provenance Details for rabbit_brain-0.8.6.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for rabbit-brain 0.8.6
File Actions
rabbit_brain-0.8.6-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for rabbit_brain-0.8.6-py3-none-win_amd64.whl
rabbit_brain-0.8.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for rabbit_brain-0.8.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
rabbit_brain-0.8.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for rabbit_brain-0.8.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
rabbit_brain-0.8.6-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for rabbit_brain-0.8.6-py3-none-macosx_11_0_arm64.whl
rabbit_brain-0.8.6-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for rabbit_brain-0.8.6-py3-none-macosx_10_12_x86_64.whl

Total release size: 58.0 MB

Release files / rabbit_brain-0.8.6.tar.gz

Download URL rabbit_brain-0.8.6.tar.gz
Size 4.0 MB
Tags Source
SHA-256 checksum
How to use checksums
12f88b5fad0d62c253b87a531b35a233b9bc2490562e2dc4770d596df887f552
BLAKE2b-256 checksum
How to use checksums
c2256418b2c528a0478c57e85c283afc4e230dbe3e7be5fe5ba8a959cd04f452
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / rabbit_brain-0.8.6-py3-none-win_amd64.whl

Download URL rabbit_brain-0.8.6-py3-none-win_amd64.whl
Size 11.7 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
95541634f53acc59a2fc33f0c513bc88b3652076dd16f7aad7ce01d13eb506f5
BLAKE2b-256 checksum
How to use checksums
f8a6ddc86d067ffc48be81a8b7d5ea570bc9d143720b753d429221e0df43e998
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / rabbit_brain-0.8.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL rabbit_brain-0.8.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 11.1 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
edf02cb437c8259ff9b0db1596deb4023c93350f7462d8a4d73d3782077c930e
BLAKE2b-256 checksum
How to use checksums
0f95c9f23c29bd7bb812c4037c2b025bf35ece3f463923cea82a159a4a66cd26
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / rabbit_brain-0.8.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL rabbit_brain-0.8.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 10.4 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b09c1c49f167616e19bbfc32a9e5d1ecad2b3865d2a60ba50e80d3815af73518
BLAKE2b-256 checksum
How to use checksums
10b7e38d28d0c38cee677cfa5512a035e3d41419c6681f7947e23d537b1f9b1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / rabbit_brain-0.8.6-py3-none-macosx_11_0_arm64.whl

Download URL rabbit_brain-0.8.6-py3-none-macosx_11_0_arm64.whl
Size 10.2 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
12cf7eccaf77ec3f71e66ddcb3e2f9ecaf3d1fde7d31ef40e020809ca1c08baa
BLAKE2b-256 checksum
How to use checksums
117da2d52de94b38c223dc5a826cb1ff1e155650beac6d4d8024460c8482ea4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / rabbit_brain-0.8.6-py3-none-macosx_10_12_x86_64.whl

Download URL rabbit_brain-0.8.6-py3-none-macosx_10_12_x86_64.whl
Size 10.6 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
966c2c7e678d47b438ff6f2c9c6e0f5372f8bc41c768f143c3e8a47577994468
BLAKE2b-256 checksum
How to use checksums
63d769f3544bc977f5c19b61fe1ba34bc0627eb645a59de46d50610332c71eae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for rabbit-brain 0.8.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page