brain

brain governs how an AI coding assistant works. For the current project and machine it assembles the rules the assistant should follow, delivers them throughout the session, and enforces the non-negotiable ones on every tool call — deterministically, without relying on the assistant to remember them. It currently targets Claude Code and GitHub Copilot CLI.

The rules themselves are authored separately and are not part of this repository.

Installation

brain is distributed as a plugin, one per harness it targets. Each plugin brings its own runtime, so you do not need Bun or jq installed. Follow the guide for your harness:

• Install brain in Claude Code
• Install brain in GitHub Copilot CLI

With the plugin installed, brain runs on its own; you supply the rules by authoring layers. See Create a layer and the reference, or follow the tutorial for your harness to build one end to end.

Documentation

The full documentation set is published at https://man.sr.ht/~cpradog/brain:

• Documentation home — overview and map of the docs.
• Tutorials — author your first layer and watch it materialize.
• How-to guides — task recipes for installing brain, authoring rules, and working on brain itself.
• Reference — the layer, rule, topic, and predicate format, the brain command, and the plugin and guard contracts.
• Explanation — how brain works and why it is built this way.

Development

Working on brain from source requires Bun (1.3.x, pinned in dependencies.pin) and jq. End users need neither — the published plugin brings its own runtime. For the format, typecheck, and test commands see Check a change to brain; to have a harness run your working copy, see the guide for Claude Code or GitHub Copilot CLI.

Contributing

Development happens over email on the sr.ht mailing list. Patches are sent with git send-email; you do not need a sr.ht account to contribute.

1. Clone the repository:

   git clone https://git.sr.ht/~cpradog/brain
   cd brain

2. Make your change on a local branch, keeping commits focused. Commit messages follow Conventional Commits (feat:, fix:, docs:, …), matching the existing history.

3. Before sending, make sure bun run format:check, bun run typecheck and bun run test pass.

4. Send the patch to the list. The list is shared across projects, so set a subject prefix once:

   git config sendemail.to '~cpradog/[email protected]'
   git config format.subjectPrefix 'PATCH brain'
   git send-email -1            # the last commit
   # for a series, send a range, e.g.:
   git send-email <base>..HEAD

If you have not used git send-email before, https://git-send-email.io walks through the one-time setup.

Bug reports

File bugs and feature requests on the issue tracker: https://todo.sr.ht/~cpradog/brain, or by email to ~cpradog/[email protected].

Please include:

• what you did, what you expected, and what happened instead;
• the harness you run brain in, and the brain version it reports — /brain:doctor in Claude Code, brain doctor in Copilot CLI;
• your operating system and architecture;
• any relevant hook or materializer output.

Resources

• Project hub: https://sr.ht/~cpradog/brain
• Source: https://git.sr.ht/~cpradog/brain
• Patches and discussion: https://lists.sr.ht/~cpradog/public-inbox (~cpradog/[email protected])
• Issue tracker: https://todo.sr.ht/~cpradog/brain

License

brain is licensed under the European Union Public Licence v1.2 (EUPL-1.2). See LICENSE for the full text. Contributions are accepted under the same licence.