Install¶
brainrc is a Python command. The quickest way to get it is uv, which also fetches a Python 3.11+ if your machine has none. You need git too: brainrc uses it to fetch packs.
Install with uv¶
uvx brainrc status # try it first: lists what apply would write, writes nothing
uv tool install brainrc
brainrc apply
brainrc status # prints "Everything in sync."
That's it. apply writes into each AI tool installed on this machine and skips the others.
Run brainrc init before apply if you want to choose which tools brainrc manages, or how much it
installs; getting started walks through it.
If your shell can't find brainrc after the install, run uv tool update-shell and open a new
shell.
Other ways to install¶
| How | Command | Notes |
|---|---|---|
| pipx | pipx install brainrc |
Same as uv. If brainrc isn't found, run pipx ensurepath. |
| Homebrew | brew install brainrc/tap/brainrc |
From the brainrc/homebrew-tap tap. |
| npx | npx github:brainrc/brainrc status |
Runs brainrc through uvx, so it needs uv but no Python. Good for a one-off run, not for apply. Keep the github:: brainrc isn't on npm. |
| Claude Code plugin | /plugin install brainrc@brainrc |
Claude Code only, no rules or packs. See plugins. |
| A clone | git clone https://github.com/brainrc/brainrc |
For changing brainrc itself. See below. |
Run apply from an installed command, not from uvx or npx: apply links your tools into
the installed package, and those two run brainrc from a cache that can be cleared.
Pin a version¶
Install a given release with uv tool install brainrc==<X.Y.Z> (or pipx install brainrc==<X.Y.Z>,
uvx brainrc@<X.Y.Z>, npx github:brainrc/brainrc#v<X.Y.Z>). Releases are listed on
PyPI and in the CHANGELOG.
Update¶
uv tool upgrade brainrc # or: pipx upgrade brainrc, brew upgrade brainrc
brainrc apply --repair
--repair relinks anything that still points at the old version. Moving packs to newer commits
is a separate step, brainrc update (upgrading).
Coming from the old names, ai-config or spec-agent? Upgrading has the steps.
Uninstall¶
brainrc uninstall --dry-run # see what goes
brainrc uninstall # remove everything apply put into your tools
uv tool uninstall brainrc # or: pipx uninstall brainrc, brew uninstall brainrc
uninstall keeps your own settings, hooks and MCP servers, and puts back any instructions file
init moved aside. uninstall --purge also deletes brainrc's own folder (~/.config/brainrc):
your local config and the packs it fetched (troubleshooting).
From a clone¶
Clone brainrc when you want to change brainrc itself. Run the same commands through
scripts/brainrc.py:
git clone https://github.com/brainrc/brainrc ~/brainrc
cd ~/brainrc
python3 scripts/brainrc.py init # optional: pick tools and a profile
python3 scripts/brainrc.py status
python3 scripts/brainrc.py apply
Two things differ from an installed command:
- Your local files live in the checkout (
harnesses.local.toml,packs.local.toml,brainrc.local.toml,rules/*.local.md), not in~/.config/brainrc/. Git ignores them. - Links point into the checkout, so
git pullupdates every tool at once. Re-runapplyafter a pull that changes rules, since rules are rendered, not linked. To stay on a release, check out its tag (git checkout v<X.Y.Z>) and re-runapply.
If you move the checkout, run python3 scripts/brainrc.py apply --repair from the new place.
CONTRIBUTING.md covers the checks to run before a pull request.
Platforms¶
macOS and Linux. brainrc installs by symlink, so on Windows use WSL, or turn on Developer Mode and
run git config --global core.symlinks true before you clone anything. validate and doctor
say when symlinks don't work, with the fix. Native Windows support is on the
roadmap.