Troubleshooting¶
Start here: doctor lists what's wrong with the install on this machine and how to fix each
item. It changes nothing.
brainrc doctor
Then find the symptom below. From a clone, run python3 scripts/brainrc.py wherever this page
says brainrc.
A harness doesn't see a skill, agent, command, or rule¶
Run brainrc apply. Skills, agents, and commands are symlinks, so edits to
existing ones show up at once, but new or removed ones need apply. Rules are different:
they're rendered into ~/.config/brainrc/instructions.md, so every change to a rule needs
apply, edits included; status lists instructions.md as UPDATE until you do. Start a new session
in the tool afterwards.
If you moved a clone or upgraded brainrc, the old links are broken and apply reports each as a CONFLICT. Run
brainrc apply --repair from the new location: it relinks every broken link
that points at the same item's old location (skills/<name>, agents/<name>.md, ...) and prunes
the ones into the old location whose item is gone. status --repair shows the changes first. A
broken link to anything else stays a CONFLICT, and your own working links are never touched.
Every skill shows up twice, or a hook runs twice¶
Both the plugin and the brainrc command's links are installed. doctor warns when it sees both
in Claude Code or Cursor, and names which to remove. Keep one: in Claude Code, /plugin uninstall
brainrc@brainrc (the links also bring the rules and your packs), or set [claude] enabled = false
in harnesses.local.toml and run apply. In Cursor, keep the plugin (it brings the rules) and set
[cursor] enabled = false, or remove ~/.cursor/plugins/local/brainrc.
If doctor warns that the old plugin ai-config@ai-config is installed, you have the plugin
under both names: follow Moving from ai-config.
CONFLICT in status or apply¶
A real file, or a symlink pointing outside brainrc and your packs, sits where brainrc wants
a link. brainrc never overwrites it. Look at it, then either:
- move it into a pack (as a skill, agent, or command) and delete the original, or
- delete it if you don't need it,
and run apply again. CONFLICT on a settings file means it isn't valid JSON: fix it by
hand. CONFLICT naming an MCP server means your harness config already defines a server of that
name: rename or remove yours (or the registry's), then run apply.
Config errors¶
status, apply, validate, and doctor check harnesses.toml, packs.toml, their
.local.toml overrides, and each pack's pack.toml first, and name the file and line:
| Message | Fix |
|---|---|
ERROR harnesses.local.toml:3: invalid TOML: Invalid value |
Fix the TOML on that line (often a missing value or quote). |
ERROR harnesses.local.toml:2: `claude` must be a table, e.g. [claude] |
Write [claude] on its own line, then enabled = false under it. |
ERROR harnesses.local.toml:3: [codex] `enabled` must be true or false |
Use true or false without quotes. Paths and ref must be quoted strings. |
WARN harnesses.local.toml:2: unknown key `enabeld` in [claude] |
A typo: the key is ignored until you fix it. |
WARN harnesses.local.toml:4: unknown harness [cursr] |
A typo, or a harness harnesses.toml doesn't list. It still loads. |
Errors stop the command before it writes anything; warnings don't.
Pack errors¶
| Message | Fix |
|---|---|
pack name `acme` is used by both [work] and [acme] |
Two packs share one name. Change name in one pack.toml, or set enabled = false for one in packs.local.toml. core is taken. |
skill `acme-deploy` is defined in both acme and acme2 |
Rename one. Each pack's items carry its own prefix. |
acme:skills/x: pack skills must start with `acme-` |
Rename the item to start with the pack's prefix. |
acme:pack.toml: `prefix` must be ASCII lowercase letters, digits and hyphens, ending with '-' |
Fix prefix in pack.toml, e.g. acme-. |
acme:pack.toml: `prefix` `aws-` uses the vendor name `aws`, ... reserved for official packs, ... one or two edits from the official name `brainrc` |
Rename the pack or its prefix to follow the naming rules. |
acme:pack.toml: requires_core `>=2.0` is not satisfied by core 1.2.3 |
Upgrade brainrc (upgrading) or the pack, or set enabled = false for it in packs.local.toml. |
pack acme: no pack.toml at ... |
Fix the pack's path in packs.local.toml. |
validate reports all of these. apply and status check each pack the same way first and
write nothing while any of them stands, naming validate --pack <dir> for the pack to fix. See packs.md.
Settings backups¶
Before apply changes a harness's settings file (Claude Code: ~/.claude/settings.json), it
copies it next to the original as settings.json.bak-brainrc-<UTC time>. The last 5 are kept, counting
old settings.json.bak-aicfg-<UTC time> backups too.
No backup is made when the file didn't exist yet. MCP config files (~/.claude.json and the
others) are backed up the same way.
The rewritten file and its backup keep the original's permissions, so a 0600 ~/.claude.json
stays 0600. If the path is a symlink (a dotfiles-managed settings.json), apply writes
through to the link's target and leaves the link in place; the backup goes next to the target.
Apply while something else writes¶
Close Claude Code before apply changes MCP servers: it rewrites ~/.claude.json while it runs.
| Message | Fix |
|---|---|
ERROR another brainrc apply is running (lock: <path>) |
Another apply (or update) holds $BRAINRC_HOME/apply.lock. Let it finish, then re-run. The lock is released when that process exits, even if it crashed, so there is nothing to delete. |
CHANGED <harness> <file> (changed during apply; close Claude Code and re-run) |
The file changed after apply read it, so apply left it alone and exited 1. Close the harness that writes it, then re-run. |
Uninstall¶
brainrc uninstall --dry-run # see what goes
brainrc uninstall
uninstall removes every link brainrc made (broken ones too), takes its hooks out of each
settings file and the MCP servers it added out of each MCP file, and removes the files and
directories that leaves empty. Your own settings, hooks, and servers stay, every file it
rewrites is backed up first (*.bak-brainrc-*), and an instructions file init moved aside is
put back. It reads which harnesses and source roots apply used from $BRAINRC_HOME/harnesses.json,
so it still works after you move or delete the checkout or a pack.
Your local config (harnesses.local.toml, packs.local.toml, rules/*.local.md) and fetched
git packs stay in $BRAINRC_HOME; uninstall --purge deletes that directory too, unless it
holds files brainrc didn't make (then it says which, and leaves them). Then remove the command:
uv tool uninstall brainrc (pipx uninstall brainrc, brew uninstall brainrc), or delete the
clone.
Every tool call is blocked, or doctor says hook missing¶
In older installs, a hook whose script had gone (checkout moved or deleted, package removed, Python
upgraded) exited 2, which Claude Code treats as a block on every tool call. Run apply to
rewrite the hook commands: they now skip a missing script (Cursor's reply "allow"), so the
harness keeps working. That also means the guard is off until it's fixed, so doctor checks
each one:
| Finding | Fix |
|---|---|
<harness>: hook missing: <path> |
Run apply from the checkout or install you use now; it re-links the hooks dir. |
<harness>: hook <path> exits <n> on an empty payload |
Run python3 <path> and read the error (often a Python too old for the guard), then apply. |
<harness>: hook <path> timed out after <n>s |
Run it by hand to see where it hangs. |
<harness>: hook <path> can't run: python3 is not on PATH |
Install Python 3, or put python3 on the PATH the harness starts with. |
A guard hook blocked something safe, or missed something risky¶
The Claude Code hooks match command patterns (guardrails.md), so both happen.
Open an issue with the exact command or tool call,
what the hook did, and what you expected.
A fix comes with two tests in tests/test_hooks.py: the risky command, and a safe near-miss
that must still pass (for example git push origin x asks, git log doesn't).