Dotbrain

English | 简体中文

Private project context for your coding agents.

Supports Claude Code, Codex, Hermes, OpenCode, Pi, and Cursor CLI.

Dotbrain brings the Dotfiles convention to your project work. Keep your working notes, plans, instructions, and selected agent resources in a private home, then wire them into the checkouts where you work.

Your context stays in local files with its own Git history. The CLI connects your workspace to the code repo; bundled workflow skills guide how your agent uses and maintains it with you.

https://github.com/user-attachments/assets/540e8945-b8bc-4fc1-ac05-c125bf768fa9

Documentation · Getting started · The workflow

Why I built it

Global agent instructions describe how I want my agent to behave at user level. Shared repository instructions describe how anyone should work on the code. My own reasoning, working notes, and plans for a particular project need a private home.

Mine were scattered across Obsidian, gitignored notes, and agent memory. Finding that context and bringing it into another session took effort. So did making my selected skills and subagents available in a new checkout. I built Dotbrain to keep that project workspace together and make connecting it to where I work repeatable.

Read the story behind Dotbrain: Dotfiles for Your Repo.

Is this for you?

Use Dotbrain when you need a private project workspace you want to keep developing across agents, sessions, or worktrees: context you've built up, plans in progress, and your own instructions and selected skills for the work.

It works alongside your agent's memory system and other context tools. The workspace is yours; you decide which outcomes belong in shared repository docs or public proposals.

If a few standing instructions in AGENTS.md or CLAUDE.md cover your needs, keep it simple.

Get started

Setup depends on your coding agent. Claude Code and Codex use marketplace plugins; Hermes, OpenCode, Pi, and Cursor CLI use CLI-based setup. You do not need to clone this repo.

Claude Code — send these as two separate prompts:

/plugin marketplace add arminzou/dotbrain
/plugin install dotbrain@dotbrain

Codex:

codex plugin marketplace add arminzou/dotbrain
codex plugin add dotbrain@dotbrain

In Codex, open /hooks, trust the dotbrain hook, then start a new thread. Hermes, OpenCode, Pi, and Cursor are supported through the CLI rather than a marketplace. On Windows, enable Developer Mode before wiring so Dotbrain can create directory symlinks without Administrator privileges.

Then ask your agent:

Use wire-brain to wire this repo with Dotbrain.

The skill installs the matching CLI, uv, and Beads if needed, prepares the machine, and wires the repo to its private Brainspace. Check the result with:

dotbrain doctor

Start a fresh agent session in the wired repo to load the Dotbrain convention. It tells the agent where to find your project context and how to work with it. See Getting started for manual installation, backups, a second machine, and troubleshooting.

Update

For Claude Code and Codex, update the plugin and the CLI together. In Claude Code, run /plugin, update dotbrain from the menu, then /reload-plugins. In Codex:

codex plugin marketplace upgrade
codex plugin add dotbrain@dotbrain

Then upgrade the CLI and reconcile your machine and projects:

uv tool install dotbrain@latest
dotbrain bootstrap
dotbrain refresh --all

Installed the CLI with pipx or pip? Upgrade with that tool instead. See Staying current. For Hermes, OpenCode, Pi, and Cursor CLI, upgrade the CLI and run dotbrain bootstrap to update their integrations; see the runtime-specific setup guides linked above.

How it works

Each project has a Brainspace under your private dotbrain home, by default ~/dotbrain/. It holds the Brain (.brain/: local Markdown files for project rules, vocabulary, decisions, and designs) and an execution store (.beads/: issues tracked with Beads). Gitignored symlinks make both available through the checkout while their files and history stay outside the code repo.

The diagram uses Claude Code and Codex as examples; all supported runtimes share the same Brainspace model.

Wiring also makes selected skills available in each configured runtime's project skill directory. Dotbrain delivers native subagents for Claude Code and Codex: Claude resources under .claude/, Codex skills under .agents/skills/, and Codex agents under .codex/agents/. Codex configuration stays in .codex/. Skills and Claude agents use symlinks; Codex agents use generated, Git-ignored TOML files. Wiring a Git worktree connects it to the main checkout's existing Brainspace, so both use the same knowledge and tracker. Hermes, OpenCode, Pi, and Cursor CLI receive skills and session integrations, but no Dotbrain native subagents.

At session start, the runtime integration supplies only DOTBRAIN.md, the shared convention. See Runtime notes for how context loading and sync differ between runtimes. Public AGENTS.md routes making or reviewing changes to tracked root RULES.md, usable without a Brain. The lead or sole agent searches private retrospective findings for the task and passes relevant findings through assignments; the notebook is never injected. Fresh Brains seed private AGENTS.md for a small set of personal preferences and project rules, with CLAUDE.md as its alias. The agent reads it before substantial work; it is never injected. Wiring and refresh preserve user-owned context and existing pointers. Public RULES.md holds repository requirements; private preferences stay private. See Session context for the loading sequence.

Use dotbrain projects list to discover registered projects. Inside a wired checkout, dotbrain refresh maintains that checkout and dotbrain unwire removes its wiring while retaining the shared Brainspace. From elsewhere, select --project <name>; use refresh --all for registered projects. Machine-global asset reconciliation is explicit: skills link --scope global or subagents link --scope global.

Git versions the Brain. Back it up to a private remote; the Beads database is Git-ignored and needs its own Dolt remote or shared server to back up or share issues. See Architecture, Wiring, and Beads backend for details.

The loop

Every piece of work should leave the next session better informed. Dotbrain's bundled skills carry work from idea to implementation, then return what you learned to the project's context.

The loop closes in two places:

• During the work: discoveries feed back into the active design and affected issues. An unexpected API constraint becomes a design question; once you settle it, the design and issues capture the decision before implementation continues.
• After human merge and closeout: closing the design records the evidence and preserves useful decisions and vocabulary in the Brain. The next initiative starts with that knowledge already available.

The Brain holds durable knowledge, the design holds current intent, and Beads holds execution state. Each handoff lives in a document or tracker entry that another session or agent can consult to continue the work.

You own success criteria, PR approval, merge, and release. Settle foreseeable decisions and the execution contract upfront; agents reuse complete applicable approval without another routine sign-off and work through checks, acceptance/UAT, and required reviews to a ready PR requesting your review. New scope, authority, or criteria decisions stop affected work with evidence and a recommendation. Limits survive resume. The design stays active until you ask for closeout; a PR closed without merge does not establish shipment. Use the full loop when work spans sessions or carries open questions; small changes can use just the steps they need.

See The workflow for a walkthrough and Skills for the full catalog.

Develop

The CLI is a uv-managed Python package.

git clone https://github.com/arminzou/dotbrain.git
cd dotbrain
uv sync
uv run dotbrain --help
uv run pytest

For an editable CLI, run ./scripts/dev-install.sh (or .\scripts\dev-install.ps1 on Windows), then dotbrain bootstrap. Bundled skills are authored in plugin/skills/. See the CLI reference for commands and options.

For bug reports and pull requests, see Contributing.

Released under the MIT License.