Skip to content

Configuration

Everything you set up for one machine lives in a few small TOML files that git never sees. A repo's shared setup is different: it lives in brainrc.toml at the repo root (team setup).

Where the files live

You run brainrc Local files go in
as an installed command (uv, pipx, Homebrew) ~/.config/brainrc/
from a clone the clone's root (git ignores them)

~/.config/brainrc/ is brainrc's own folder, the settings home. Set BRAINRC_HOME to move it. Whichever way you run brainrc, it renders the rules there, keeps the lock there and fetches git packs into it.

File What it sets
harnesses.local.toml which tools brainrc manages, and their paths
packs.local.toml which packs this machine adds, or turns off
brainrc.local.toml the profile, and items to leave out
rules/*.local.md rules for this machine only, loaded after all the others

brainrc init writes the first three for you. Every file is optional.

harnesses.local.toml

brainrc manages a tool when its folder exists (~/.claude, ~/.codex, ~/.config/opencode, ~/.gemini/config, ~/.cursor) and skips it otherwise. This file overrides that, one table per tool:

[cursor]
enabled = false        # leave Cursor alone, even though it's installed

[opencode]
enabled = true         # manage OpenCode before its folder exists

The table names are claude, codex, opencode, antigravity, cursor, and gemini (Gemini CLI, off by default since Antigravity CLI replaced it). A table can also change any path from harnesses.toml, such as skills or instructions, though the variables below are usually the better way.

packs.local.toml

One table per pack, by a path on disk or a git URL:

[acme]
path = "~/src/acme-ai-pack"      # ~ and $VARS expand; a relative path is relative to this file

[team]
git = "git@github.com:acme/team-ai-pack.git"
ref = "v1.2.0"                   # a tag, branch or commit; default: the remote's default branch

[gatework]
enabled = false                  # turn off the default pack
Key Meaning
path the pack's folder
git a URL to fetch instead; private repos use your git credentials
ref with git: what to fetch
enabled false removes the pack's items on the next apply
run_validator true lets a pack's own validator.py run (packs)
description a note for people; ignored

Packs has the rest: how git packs are pinned, and how to point Gatework at a clone.

brainrc.local.toml

How much this machine installs:

profile = "recommended"
exclude = ["gatework:skills/brainrc-aws", "gatework:agents/brainrc-infra-*"]
profile Installs
minimal rules only
recommended rules, skills, agents, commands and hooks
full (the default) all of that, plus the MCP servers packs define

exclude drops single items. A pattern matches an item's path in its pack (skills/brainrc-aws) or that path after the pack's name (gatework:skills/brainrc-aws), and * and ? work. brainrc init --profile <name> or --starter <name> writes this file. apply removes what a profile or pattern drops; validate still checks everything.

Local rules

Files named rules/NN-<topic>.local.md in the settings home (or the clone) are added after every other rule, under a note that they refine the rules above. They are plain markdown. Run apply after each change.

Environment variables

Variable Effect
BRAINRC_HOME moves the settings home (default ~/.config/brainrc)
XDG_CONFIG_HOME when set to an absolute path, the settings home is $XDG_CONFIG_HOME/brainrc, and OpenCode's files are under $XDG_CONFIG_HOME/opencode
CLAUDE_CONFIG_DIR moves Claude Code's files, .claude.json included
CODEX_HOME moves Codex's files

brainrc reads a tool's variable the way the tool does: an absolute path moves the files, and an unset, empty or relative one means the default. So run brainrc with the same environment as the tool. If a variable changes between two apply runs, brainrc's links stay in the old folder; apply and doctor warn about it, and uninstall cleans both.

Files brainrc keeps in the settings home

You don't edit these, but it helps to know what they are:

File What it is
instructions.md the rendered rules every tool's instructions file links to
extensions.md what packs add to Gatework, rendered for it to read
brainrc.lock this machine's lock: pack commits, file hashes and permissions
packs/ git packs apply fetched
hooks/ a copy of the guard hooks, which tools run from here
harnesses.json which tools and sources apply used, so uninstall works after a move
mcp-owned.json, mcp-pins.json the MCP servers brainrc wrote, and their pinned tools