Team setup: brainrc.toml and brainrc.lock¶
Give a repo's AI agents the same skills and rules on every machine and in CI. You commit two
files: brainrc.toml says which packs the repo uses, and brainrc.lock records exactly what they
were. apply writes the agent files into the repo itself (.agents/skills/, AGENTS.md, ...),
so every tool that opens the repo finds them, whether or not brainrc is installed there.
Set it up¶
cd my-repo
printf 'version = 1\n' > brainrc.toml # Gatework only; add packs below
brainrc apply # writes .agents/skills/, .claude/skills/ and brainrc.lock
git add brainrc.toml brainrc.lock .agents .claude
git commit -m "Add brainrc"
A teammate, or CI, then runs:
brainrc install --frozen # exactly what the lock records, or fail
brainrc check # exit 1 if anything drifted from the lock
To change what the repo uses, edit brainrc.toml and run apply, which relocks. To take newer
pack versions, run brainrc update. Commit the result either way.
The rest of this page is the full contract for both files. It is language-neutral: another
implementation that reads and writes them as described here is compatible. The JSON Schemas
schemas/brainrc.toml.schema.json and
schemas/brainrc.lock.schema.json describe each file after
it is parsed as TOML; brainrc checks both files against them on every read. Conformance
fixtures are in tests/fixtures/lockfile/.
Scopes¶
- User scope is your machine: brainrc's own content, the default pack and the packs in
packs.local.toml, linked into each installed tool's home folder. Its lock is$BRAINRC_HOME/brainrc.lock(default~/.config/brainrc/brainrc.lock). - Project scope is a repo with
brainrc.tomlat its root. Its agent files are written into the repo, and its lock isbrainrc.locknext tobrainrc.toml.brainrcfinds the project from the current directory: that directory or a parent, up to the repo root (the first directory that holds.git).
Both scopes apply together. The user's own config still layers on top of a project's at run time, because harnesses read the user's home and the repo.
What apply writes in a project¶
brainrc apply (and status, which writes nothing) runs the user scope first, then the project
in the current directory, under its own Project <dir> (brainrc.toml) heading.
- Skills are copied, not linked, to
.agents/skills/<name>/, so the repo works on every machine and in CI. A link inside a skill (Gatework'sroles/) is copied as the files it points to. - Rules from the project's packs go into a marked block in
AGENTS.md:<!-- brainrc:begin: … -->to<!-- brainrc:end -->. Your own text above and below the block stays. With no rules, there is no block, and a file that held only the block is removed. - Standard files first. Codex, OpenCode, Cursor and Antigravity read
.agents/skills/andAGENTS.mdthemselves, so they get nothing else. A tool that can't read them names its own places inharnesses.toml(project_skills,project_instructions). Today that is Claude Code only: skills are copied to.claude/skills/too, andCLAUDE.mdgets a marked block holding@AGENTS.md, unless it already readsAGENTS.md(a link to it, or its own@AGENTS.mdline).harnessesinbrainrc.tomlpicks which tools get their own files; drop one and its files and block are removed.
| Tool | Skills | Instructions |
|---|---|---|
| Codex, OpenCode, Cursor, Antigravity | .agents/skills/ |
AGENTS.md |
| Claude Code | .claude/skills/ (copy) |
CLAUDE.md block importing AGENTS.md |
- Only the project's packs: core's rules and guard hooks, MCP servers and anything
machine-local (
packs.local.toml,brainrc.local.toml,*.local.md) stay in the user scope, so they never change a project's files. - Git packs are fetched by
apply, never bystatus, into$BRAINRC_HOME/project-packs/<key>-<id>, one clone per URL and ref. - Ownership:
brainrc.locklists every filebrainrcwrote (outputs). A file there is updated or removed as its pack changes. A file brainrc didn't write, or one you changed after it was removed from the packs, is aCONFLICTand is left alone.
Pinned commits and update¶
apply resolves each git pack's ref once and records the commit in the lock. After that the
commit is pinned: apply, status and install keep the pack at the lock's commit, on this
machine and on a teammate's, even when the tag is moved or the branch (or the remote's default
branch, for a pack with no ref) moves on. A clone found at another commit is put back
(FETCH <pack> <url> (<ref>, locked at <commit>)). Changing git or ref in the config is a
deliberate move, so the next apply fetches the new ref and relocks.
brainrc update [<pack> ...] is the one command that moves a pin to what the ref resolves to now.
It refetches the named packs (every git pack when none is named; in a project, the project's packs
of that name too) and, before anything is relinked or relocked, prints for each pack:
MOVED gatework v0.7.1: 753b9960c5e0 -> 8c41d2f0a9b3 (user scope)
commit 8c41d2f Tighten the review checklist
added skills/brainrc-new/SKILL.md
changed skills/brainrc-work/SKILL.md
The commits are the ones between the old pin and the new one (up to 50; an older pin that isn't in
them is named, as a rewritten history or a longer gap), and the files are the pack's installed files
whose hash changed. CURRENT says nothing moved. Then it runs apply, which relocks. A failed fetch
applies nothing, and the next apply puts the pack back at its pin.
Installing from the lock¶
brainrc install --frozen installs exactly what brainrc.lock records, for CI and teammates. It
fetches each git pack's locked commit, never its ref, so a moved tag changes nothing. Every
check runs before anything is written: the packs in brainrc.toml (or packs.toml) and the lock
must match by key, URL, ref and path, and every file must hash as the lock says, outputs included.
On any mismatch it names each one, writes nothing and exits 1. It never rewrites the lock and
never removes files. It won't overwrite a file brainrc didn't write either: one at a locked path
whose hash is neither the lock's nor what brainrc last wrote there on this machine (kept in
$BRAINRC_HOME/project-state/), or a hand-edited block in AGENTS.md. It names each one and
writes nothing; --force overwrites them. Neither writes through an AGENTS.md that is a link.
The scope is the project when there is a brainrc.toml here or above, else the user; --scope user|project picks one. brainrc install without --frozen is apply.
Checking for drift in CI¶
brainrc check exits 1 when anything differs from brainrc.lock, naming each difference: a pack
in brainrc.toml the lock doesn't have (or the reverse), a pack file this machine has that hashes
differently, a file brainrc owns in the repo that was edited, removed or added to, and its block in
AGENTS.md. It uses no network and writes nothing. A git pack not fetched on this machine is checked
through the repo's files; a clone at another commit than the lock's is reported as MOVED and
doesn't fail (apply puts it back).
- uses: actions/checkout@v4
- name: Agent files match brainrc.lock
run: pipx run brainrc check
brainrc install --frozen after it also fetches each git pack at its locked commit and checks it.
brainrc.toml¶
version = 1 # optional; 1 is the only version
exclude = ["gatework:skills/brainrc-aws"] # optional; items to leave out (see below)
harnesses = ["claude", "codex"] # optional; tools that get their own files
[packs.gatework] # a default pack: on unless `enabled = false`
ref = "v0.7.1" # pin it to another ref; its `git` URL is kept
[packs.acme]
git = "https://example.com/acme/agent-pack.git"
ref = "v2"
[packs.team]
path = "tools/agent-pack" # relative to the repo root
| Key | Type | Meaning |
|---|---|---|
version |
integer | Format version. 1, the default. |
exclude |
array of strings | Items not to install, as a path in the pack (skills/brainrc-aws) or after its name (gatework:skills/brainrc-aws); * and ? match. |
harnesses |
array of strings | Harnesses (from harnesses.toml) that get tool-specific files besides the standard ones. Default: every enabled harness in core's harnesses.toml (never harnesses.local.toml); [] for the standard files only. |
packs.<key> |
table | One pack. <key> is lowercase letters, digits and -. |
packs.<key>.enabled |
boolean | Default true. false turns a default pack off. |
packs.<key>.git |
string | A URL to fetch. Can't start with -. |
packs.<key>.ref |
string | With git: tag, branch or commit. Default: the remote's default branch. |
packs.<key>.path |
string | A directory inside the repo, relative to the repo root, using /. No .., ~, $ or leading /. |
packs.<key>.description |
string | A note for people; ignored. |
- Default packs are the tables in core's
packs.toml(Gatework). They are on in every project unlessbrainrc.tomlsetsenabled = false. Arefalone keeps the default pack's URL;gitorpathreplaces its origin. - Any other pack needs exactly one of
gitandpath. - Unknown keys are errors, so a typo never silently changes what is installed.
brainrc.lock¶
apply writes it; nobody edits it. A second apply with no change to any source leaves it
byte-identical.
# brainrc.lock: written by brainrc. Don't edit it by hand.
version = 2
brainrc = "0.7.3"
scope = "project"
[packs.gatework]
git = "https://github.com/brainrc/gatework.git"
ref = "v0.7.1"
commit = "753b9960c5e0d2f1a4b7c8e9d0a1b2c3d4e5f607"
[packs.gatework.files]
"agents/brainrc-analyst.md" = "sha256:3f1c…"
"skills/brainrc-work/SKILL.md" = "sha256:9a0b…"
[packs.team]
path = "tools/agent-pack"
[packs.team.files]
"skills/team-deploy/SKILL.md" = "sha256:5d2e…"
[outputs]
".agents/skills/brainrc-work/SKILL.md" = "sha256:9a0b…"
[blocks]
"AGENTS.md" = "sha256:77c4…"
| Key | Type | Meaning |
|---|---|---|
version |
integer | Format version, 2. Version 2 adds packs.<key>.permissions; brainrc reads 1 and 2 and writes 2. A reader refuses a newer version and names the brainrc that wrote it, so brainrc 0.7.7 and older say to upgrade instead of failing on permissions. |
brainrc |
string | The brainrc version that wrote it, MAJOR.MINOR.PATCH. |
scope |
string | user or project. |
packs.<key> |
table | Every enabled pack, and nothing for a disabled one. |
packs.<key>.git |
string | The URL fetched, with any user name or password removed. |
packs.<key>.ref |
string | The ref asked for (HEAD when the config names none). |
packs.<key>.commit |
string | The commit that ref resolved to: 40 or 64 lowercase hex digits. Git packs only. |
packs.<key>.path |
string | A path pack's directory as the config wrote it; under the home directory it is written with ~. Path packs have no commit. |
packs.<key>.files |
table | Every installed file of the pack (below): its path in the pack, using /, to its hash. |
packs.<key>.permissions |
table | What the pack can do in this scope (permissions): hooks, mcp, tools, domains, each a sorted array of strings, present only when not empty. |
outputs |
table | Project scope: every file brainrc wrote into the repo, repo-relative, to its hash. |
blocks |
table | Project scope: files brainrc shares with you (AGENTS.md): the hash of its marked block. |
A hash is sha256: and 64 lowercase hex digits, the SHA-256 of the file's bytes. A pack has
exactly one of git (with commit) and path. outputs and blocks appear only in a
project lock, and only when they have entries; empty files tables are written too.
A pack's installed files are the files brainrc reads from it to install: pack.toml, the
file its validator names, rules/*.md (not README.md or *.local.md), each item it installs
(every file under skills/<name>/, agents/<name>.md, commands/<name>.md) after the profile
and exclude are applied, and, in user scope with hooks installed, every file under
overrides/. Symbolic links are followed, so a file is hashed as it is read. __pycache__
directories are skipped.
Determinism. The lock is UTF-8 with \n line endings and ends with one newline. The first
line is the comment above. Then come version, brainrc and scope, in that order. Then one
[packs.<key>] table per pack sorted by key, its keys in the order git, ref, commit, or
path, each followed by its [packs.<key>.files] table and its
[packs.<key>.permissions] table (arrays written one string per line, sorted). Then [outputs] and [blocks]. Every
table's entries are sorted by key (by Unicode code point). Keys that aren't bare keys
(A-Za-z0-9_-) are written as basic strings. Strings escape ", \ and control characters as
TOML basic strings do. The lock holds no timestamps, no host or user names, no credentials and
no absolute path to the home directory.
Ready for more. Future keys (pinned commands, more permission records) are added inside
packs.<key> or as new top-level tables, with a version bump only for a change an old reader
would misread.
Permissions¶
The lock records what each pack can do in its scope, so a pack can't widen it unseen:
| Field | Entries |
|---|---|
hooks |
Each hook its overrides/<harness>/settings.fragment.json adds: <harness> <event> [<matcher>] <command>. User scope, when the profile installs hooks. Also brainrc validator <file> when pack.toml names a validator, in both scopes. |
mcp |
Each MCP server in its mcp/servers.toml: name, URL or command and arguments, the variables it reads and its harnesses. User scope, full profile. |
tools |
Each installed agent's tools (an agent without them gets (every tool)), each skill's and command's allowed-tools, the fragment's permissions (<harness> allow <rule>, deny, ask), and any other key it sets with its value (<harness> sets statusLine = {...}; a sha256 when over 200 characters). |
domains |
Each host the pack's MCP URLs and domain: grants name. |
status prints PERMS <pack> + <kind> <entry> for what apply would add and - for what it would
remove. apply (and update, and install without --frozen) asks before writing anything when
any entry is added or a deny or ask rule is removed, and --yes accepts them. Without a terminal
to ask in (CI, a script, a pipe) and without --yes, it refuses and writes nothing; there is no
variable that skips the question. Removing any other entry never asks. When update is refused,
the git packs it moved go back to the commits the lock pins, since the harnesses link into them.
A machine's first lock has nothing to widen from: its permissions are listed once as PERMS lines
and recorded as the baseline. A pack added to an existing lock is a widening. A pack entry in a lock
written before permissions were recorded has none; it counts as the baseline only while the pack's files
still hash as that lock says, and never for MCP servers and their hosts, since mcp/servers.toml
isn't among the hashed files. install --frozen installs only what the lock records, so it never
asks and takes no --yes: a widening fails it, and apply is where to review and accept it.