Dotbrain

Private project context for Claude Code and Codex.

Give each coding agent your project's decisions, vocabulary, and issues. Keep that context versioned and outside your code repo.

Documentation · Getting started · The workflow

Why I built it

I built Dotbrain because my projects often start privately and get shared later. The code can be shared; the half-formed decisions, roadmap, and rationale need their own home. Mine scattered across Obsidian, gitignored notes, and agent memory. Every new session meant hunting for context and explaining the project again. I wanted that thinking versioned, available to both agents, and connected to the work.

Is this for you?

Use Dotbrain if you work across agents, sessions, or worktrees and have project context worth preserving. It gives that context a home you can review and version with Git, separate from the code you share.

If a few standing instructions in AGENTS.md or CLAUDE.md cover your needs, keep it simple. Dotbrain is a local tool, not a hosted team knowledge base.

Get started

Install the plugin into your coding agent. 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. 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 its Brain context. See Getting started for manual installation, backups, a second machine, and troubleshooting.

How it works

Each project has a Brainspace under your private dotbrain home, by default ~/dotbrain/. It holds the Brain (vocabulary, decisions, and designs) and an execution store (issues tracked with Beads). Gitignored symlinks connect the code repo to that Brainspace; the private files are stored outside the code repo.

The plugin's session-start hook loads project context. Its skills guide work when invoked, and wiring delivers selected skills and subagents into the repo's agent workspaces. Skills and Claude agents use symlinks; Codex agents use generated, Git-ignored TOML files. dotbrain wire connects worktrees to the same Brainspace through Git metadata.

Use dotbrain projects list to discover registered projects. Inside a wired checkout, dotbrain refresh maintains that checkout and dotbrain unwire detaches it 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 agents 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.

Start from the Brain → explore unknowns → settle decisions → write a design → work and verify issues → review → return lasting decisions to the Brain.

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 review: 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, so another session or agent can pick up the work without reconstructing it from chat history.

You own the success criteria and the final review decision. 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.