Skip to content

Concepts

The few words the rest of these docs use, in plain terms.

Harness

An AI coding tool that reads config from your disk: Claude Code, Codex CLI, OpenCode, Antigravity CLI and Cursor. Each keeps its skills, rules and settings in its own folder and format. brainrc writes into the ones installed on your machine and skips the rest, unless harnesses.local.toml turns one on or off (configuration). What reaches each tool shows what each one gets.

Item

One piece of config:

  • a rule: text every session loads, such as "never push without asking";
  • a skill: a folder of instructions a tool loads when the task calls for it;
  • an agent: a role with its own prompt and tools, which another agent can hand work to;
  • a command: a slash command;
  • a hook: a script the tool runs at a set moment, such as the guard that asks before a git push;
  • an MCP server: a tool the agent can call.

Pack

A folder or git repo of items, one folder per kind (rules/, skills/, agents/, ...) and a pack.toml that names it. brainrc itself ships only rules and guard hooks; everything else comes from packs. You turn packs on in packs.local.toml, or a repo names them in its brainrc.toml (packs).

The default pack is Gatework, which takes a ticket to a pull request. It is on unless you turn it off. Your own pack holds what you don't want in a public repo, such as your employer's conventions.

Profile

How much one machine installs from its packs: minimal (rules only), recommended (plus skills, agents, commands and hooks) or full (plus MCP servers, the default). It lives in brainrc.local.toml, with an exclude list to drop single items, and brainrc init asks for one (configuration).

Lockfile

brainrc.lock records exactly what was installed: each git pack's commit and a SHA-256 hash of each file. brainrc keeps a pack at its locked commit until you run brainrc update, so a moved tag or branch never changes what you have. A repo commits its lock next to its brainrc.toml, and every machine and CI job installs the same files (brainrc install --frozen), while brainrc check fails when anything drifted (team setup).

Scope

Where the files go. User scope writes into each tool's home folder (~/.claude/, ...): core, the default pack and the packs in your packs.local.toml. Project scope writes into a repo that has a brainrc.toml (.agents/skills/, AGENTS.md, ...), so everyone on the team gets the same agent setup. apply does both: the user scope first, then the project you are in.

Core

brainrc's own repo: the command, its rules (rules/), the guard hooks (overrides/) and the list of where each tool reads its config (harnesses.toml). Packs declare which core versions they work with (requires_core).

status and apply

brainrc status shows what would change and writes nothing. brainrc apply makes the change: it links items into each tool, renders rules into one file per tool, and merges hooks and MCP servers into the tool's settings while keeping yours.