Why packs, and what you trust when you turn one on¶
A pack is the unit brainrc shares instructions in. This page explains why it's a separate unit from brainrc itself, and what keeps a pack you didn't write from doing more than you agreed to.
Why a pack, not a fork¶
brainrc's own rules and hooks are generic: they say how an agent should work anywhere. What an agent needs to know about one employer, team or stack (its hosts, ticket keys, review rules, domain skills) changes on another schedule and often can't be public. Keeping that in a pack means brainrc can be updated without merging into your copy, and a pack can be private, versioned and owned by the people who know its subject.
One pack also reaches every tool. A pack's skills, agents, commands, rules, hooks and MCP servers
are written once, and apply renders them into each harness's own format and place. The same
pack listed in a repository's brainrc.toml gives every agent that opens the repository the same
files, through AGENTS.md and .agents/skills/, whether or not each person runs brainrc.
Rules cost every session; skills cost one¶
A rule is loaded into every session on every machine with the pack, so it is paid for whether or
not the task needs it. A skill's description is loaded, and its body only when a task calls for
it. That is why new pack writes one short rule that points at a facts skill, and why
max_always_tokens and brainrc tokens exist: the budget is shared with every other pack and
with the work itself (context cost).
The trust model¶
Turning a pack on runs its hooks, starts its MCP servers and puts its text in front of your agents. brainrc can't judge whether that text is good advice, so it makes sure you can see what a pack can do, that it can't change unseen, and that its code runs only where you chose.
- Names say who it's from.
brainrc-andbrainrc/belong to official packs, a published pack's prefix starts with its owner's handle, and names one or two edits from an official name or using a vendor's are refused. Every item starts with its pack's prefix, so one pack can't replace another's skill (naming). - What it can do is in the lock.
brainrc.lockrecords each pack's hooks, MCP servers, tool grants and the hosts they reach.applyshows aPERMSline for each new one and asks before writing; in CI, with no one to ask, it refuses.install --frozeninstalls only what the lock holds (permissions). - What it is can't move. The lock pins each git pack to a commit and every file to a hash.
brainrc checkfails when a file differs, with no network;updateis the one command that moves a pack, and it shows what changed first (pinned commits). - Its code runs only where you chose. A pack's validator runs inside brainrc only for a
default pack, for
validate --pack, or when you setrun_validator = truefor it. Its tests run only fromvalidate --packon the command line, never fromapplyordoctor(validator plugins, pack tests). - It says which brainrc it fits.
requires_corestopsapplywriting anything when brainrc is outside the range the pack was tested with (compatibility). - Old mistakes stay fixed. A pack's tripwires fail
validatewhen a retired tool, host or path comes back in any file (tripwires).
None of this reviews a pack's instructions for you. Read a pack's rules and hooks before you turn it on, the way you'd read a dependency's install script, and pin it to a tag or commit.
Packs and Claude Code plugins¶
brainrc also ships as a Claude Code plugin (plugins), but packs need the
brainrc command: a plugin could carry a pack's skills, agents and hooks, but not its rules or
its Gatework extensions (domains, ticket connector, Deliver checks), which brainrc apply
renders, and it reaches only Claude Code. This may change if plugins gain a way to extend another
plugin. To move a plugin of your own into a pack, see from a plugin.