Skip to content

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.toml at its root. Its agent files are written into the repo, and its lock is brainrc.lock next to brainrc.toml. brainrc finds 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's roles/) 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/ and AGENTS.md themselves, so they get nothing else. A tool that can't read them names its own places in harnesses.toml (project_skills, project_instructions). Today that is Claude Code only: skills are copied to .claude/skills/ too, and CLAUDE.md gets a marked block holding @AGENTS.md, unless it already reads AGENTS.md (a link to it, or its own @AGENTS.md line). harnesses in brainrc.toml picks 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 by status, into $BRAINRC_HOME/project-packs/<key>-<id>, one clone per URL and ref.
  • Ownership: brainrc.lock lists every file brainrc wrote (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 a CONFLICT and 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 unless brainrc.toml sets enabled = false. A ref alone keeps the default pack's URL; git or path replaces its origin.
  • Any other pack needs exactly one of git and path.
  • 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.