Skip to main content

brainrc

Write your AI-tool config once and sync it into Claude Code, Codex CLI, OpenCode, Antigravity CLI, and Cursor. Skills reach all five tools. Rules, commands, agents, hooks, and MCP servers reach only some, because the tools differ (harness support).

Quickstart

Needs uv and git; uv fetches a Python if you have none.

uvx brainrc status
uv tool install brainrc     # or: pipx install brainrc
brainrc apply
brainrc status

The first status previews what apply would write and writes nothing. It worked when the last status prints Everything in sync.

$ uvx brainrc status
CREATE    claude    ~/.claude/skills/brainrc-aws
...                 (about 160 lines, one per file)
MERGE     cursor    ~/.cursor/hooks.json  (hooks)

Dry run. Run `apply` to write.
$ brainrc apply
CREATE    claude    ~/.claude/skills/brainrc-aws
...
MERGE     cursor    ~/.cursor/hooks.json  (hooks)
$ brainrc status
Everything in sync.

Install

In Claude Code, the quickest path:

/plugin marketplace add brainrc/brainrc
/plugin install brainrc@brainrc

It carries the guard hooks; Gatework (spec-agent) is its own plugin, gatework@gatework. Plugins cover Claude Code only. For the other tools, rules and private packs, use the brainrc command above. All install paths, platform notes, and pinning: docs/install.md.

Why not …

Its own docs say brainrc
chezmoi manages your dotfiles across multiple machines, securely not a dotfile manager; it targets AI-tool config and their formats
GNU Stow a dotfile organizer that symlinks separate directories into your home directory links skills and similar files the same way, but also renders rules and merges hooks and MCP servers per tool
Harness plugins a Claude Code plugin is a directory of skills, agents, hooks, and MCP servers installed as one unit ships as one too; brainrc covers the other four tools
rulesync a Node.js CLI that generates config files for many AI tools from unified rule files ships guard hooks and installs Gatework (spec-agent) as its default pack; rulesync is a Node tool, brainrc a Python one
brainrc's limits best on Claude Code; Codex, Antigravity, Cursor are best effort; needs uv (or Python 3.11+) outside Claude Code

Also see ruler and dotagents.

spec-agent

spec-agent takes a ticket to a reviewed pull request: spec → plan → implement → verify → document → deliver, run by a team of small agents, with your approval at three gates. It covers application code and infrastructure.

/brainrc-work gh:42                 # or: /brainrc-work local:tickets/7.md · /brainrc-work add a --dry-run flag to the sync CLI

You approve the spec, the plan, and delivery (push, PR, ticket update). Everything between runs on its own, with evidence at every step. It lives in Gatework, the default pack. Details: docs/spec-agent.md.

Harness support is not equal. Each role gets a fresh context, and the guard hooks are enforced, only in Claude Code. OpenCode also runs roles as real subagents, but every role uses the same model and its hooks block instead of asking. In Codex, Antigravity CLI, and Cursor, spec-agent switches roles inside one session, so its reviewers are not independent of the implementer. Treat those three as best effort (details).

More

Doc For
guardrails · post-deliver what the hooks catch and their gaps; following a PR through CI and merge
packs · tutorial · project lock private skills and rules in a separate repo; a repo's own packs, pinned in brainrc.lock
formats · troubleshooting · roadmap · architecture reference
sandbox · evals · e2e runs try spec-agent on a toy repo and grade the run

Contributing

See CONTRIBUTING.md, GOVERNANCE.md, the code of conduct, and AGENTS.md. Before committing, run python3 scripts/brainrc.py validate and python3 -m unittest discover -s tests.

Security

Treat this repo as public. Don't commit secrets, tokens, internal hostnames, or absolute home-directory paths. Gitleaks runs in pre-commit and CI. To report a vulnerability, see SECURITY.md.

Privacy

brainrc sends no usage data and has no telemetry. Its own code makes no network calls. The only external commands it runs are git, to fetch packs you name by URL, and ccusage, only if you pass --ccusage to the retro script. The eval scripts run only the model command you configure.

Metadata

Release files for brainrc 0.8.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brainrc 0.8.4
File Size Uploaded Provenance Actions
brainrc-0.8.4.tar.gz 135.6 kB With provenance Details for brainrc-0.8.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for brainrc 0.8.4
File Interpreter ABI Platform Actions
brainrc-0.8.4-py3-none-any.whl Python 3 none any Details for brainrc-0.8.4-py3-none-any.whl

Total release size: 298.5 kB

Release files / brainrc-0.8.4.tar.gz

Download URL brainrc-0.8.4.tar.gz
Size 135.6 kB
Tags Source
SHA-256 checksum
How to use checksums
bc7881621594c7c8385445cce19939c704d5b8628889fe04950770958d25b521
BLAKE2b-256 checksum
How to use checksums
452d9b6a4886a4d91dd8f6a3170fb43db6f7bd5bd4efb1e9e03f42a52314bc49
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / brainrc-0.8.4-py3-none-any.whl

Download URL brainrc-0.8.4-py3-none-any.whl
Size 163.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ccc83fbcb9f3001f2e0c1702429162f46cb3231594fb2738e86c21dfd7535f13
BLAKE2b-256 checksum
How to use checksums
d6d3069565f18770cb72d218e25e266ae7ad7e2d2d194f8e4967c51bbdc3d411
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for brainrc 0.8.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for brainrc-0.8.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page