devbrain

A shared, git-synced memory layer for AI coding agents.

How It Works · Install · Daily Use · Design

AI coding agents forget: close the chat, switch machines, or change tools, and everything they learned is gone. devbrain gives every agent working on a repo the same durable project memory.

Every prompt you send is captured to a private, git-synced markdown store you own, then distilled into a searchable brain and a task queue. The brain records what happened; the queue records what's next. Markdown + git is the source of truth; everything else is a rebuildable projection. Built for Claude Code, with the same workflows as skills in other agents (e.g. Codex).

How It Works

Brain        durable project memory, git-synced across every session and machine
 ├─ Capture     every prompt → raw markdown log     automatic, model-free · source of truth
 ├─ Distill     /distill → brain pages + queue      searchable, rebuildable
 ├─ Queue       what should happen next             one markdown file per task
 └─ Sync        many agents, one brain              keyed by git remote

devbrain install wires this machine: a one-minute timer sweeps every new Claude Code and Codex transcript into the log, then commits and pushes it to your configured remote. Capture reads the agents' own on-disk transcripts — no capture hooks, nothing to trust or break; if the machine sleeps, the next sweep catches up. Files land within a minute; the git commit+push batches to every 15 so history stays readable. The log is keyed by the repo's git remote, so all worktrees collapse to one project. devbrain is a single binary; your prompts and brain live in a separate private store at ~/devbrain-data that you own — nothing leaves your machine until you add a remote or opt into embeddings. Full design in DESIGN.md.

Install

brew install TheWeiHu/devbrain/devbrain
devbrain install

No Homebrew? go install github.com/TheWeiHu/devbrain/cmd/devbrain@latest or grab a release tarball and put devbrain on PATH.

devbrain install is idempotent and wires only this machine. In a terminal it asks y/n per component; non-interactive runs take every default. When it finishes it opens the browser dashboard (devbrain dashboard — Board · Profile). Common flags:

devbrain install --dry-run                     # preview every path it would touch; write nothing
devbrain install --explain                     # dry-run plus a one-line why per action
devbrain install --only capture                # just capture (sweep + gbrain trace)
devbrain install --no-open                     # don't auto-open the dashboard
DEVBRAIN_DATA=~/path devbrain install          # store the brain elsewhere
devbrain install --satellite                    # wire a second machine as a satellite

Satellites (a second machine / an AWS box). One curator machine owns brain rewrites; every other machine is a satellite — it reads the full brain and captures + flushes its own turns, but never curates (distill/reconcile refuse, so two machines never fight over the shared pages in git). --satellite folds devbrain role satellite into the install so a box is one command. On a headless box the flusher wires the systemd user timer over SSH (enable-linger + user-bus env — no manual loginctl dance). Flip a machine's role anytime with devbrain role satellite / devbrain role curator.

Use devbrain hosts list to inspect capture sources in the selected brain. devbrain hosts retire <hostname> silences that brain's stale warning for an obsolete machine; devbrain hosts restore <hostname> reverses it. A newer capture automatically reactivates the host. Retirement is saved in the brain's retired-hosts.json and syncs on the next flush; local capture failures still warn.

Search engine (optional). Offline devbrain brain search needs nothing. For ranked search, opt into gbrain — a separate local search engine (a global bun add -g, pinned gbrain@0.18.2) — with devbrain install --install-deps. For semantic ranking — the devbrain brain query path /continue prefers — set an OpenAI key and re-index:

export OPENAI_API_KEY=sk-...   # or: devbrain brain config set openai_api_key sk-...
devbrain rebuild               # re-indexes pages and embeds stale entries

devbrain brain search/query ranks the current repo first and keeps at most two cross-project results. Add --global to preserve the engine's all-project ordering.

Multiple Brains

Keep separate GitHub repositories for personal and work memory. Your existing data repository is named default; unassigned projects continue using it.

devbrain brains add work --repo your-org/work-brain --data ~/devbrain-work-data
devbrain brains assign work                 # assign the current code repository
devbrain brains current                     # show this project's brain
devbrain --brain default brain search "deployment"
devbrain --brain work dashboard --no-open

Omit --repo to register an existing checkout. brains assign NAME OWNER__REPO assigns another project; brains default NAME changes the default for unassigned projects. Registration and assignments live in the local Devbrain configuration; configure each capturing machine consistently. devbrain data-dir prints the selected directory for scripts.

Logs, pages, TODOs, and preferences stay within each brain. The dashboard shows all registered brains by default; its brain toggles remember your selection. Edits stay in the selected record’s brain. Use --brain NAME for a single-brain dashboard. Search uses the existing keyword reader when multiple brains are registered; the shared gbrain semantic index is disabled. --global searches all projects within the selected brain. --brain NAME overrides one command, never background routing.

Assignments apply to new sessions. Previously captured sessions keep their original destination, including on re-import; history is never moved automatically. Start a new session after changing an assignment. Global agent instructions load preferences from the selected brain, with backups of the previous instructions saved alongside them as .before-brains files.

One background sweep routes captures across the registered repositories, and flush syncs them independently. If a checkout is unavailable, capture waits for it to return rather than guessing session ownership; other repositories can still sync. Explicit --brain or DEVBRAIN_DATA selections limit import/flush to that registered brain.

Embedding sends page/log text to OpenAI's API — the one opt-in egress (SECURITY.md). Core devbrain needs only your coding agent and Git — no python3, Node, or Bun. Two optional binaries extend it: the gbrain engine (semantic search) and GitHub's gh CLI, which the GitHub-aware features use to read pull-request and CI status.

Dedicated capture hosts can set "capture_projects": ["owner__repo"] in their Devbrain config to skip unrelated transcript and query-trace captures. Session ownership is tracked per project, so a mixed-project session can span brains.

Daily Use

Command	What it does
(automatic)	every prompt swept from agent transcripts each minute; committed and pushed every 15
/distill	fold new log → brain pages and queue tasks
/continue	resume from memory, then work the top queue task into a small PR
/reconcile	mark brain facts the live repo contradicts (auto-runs ~daily)
/audit	spot-check recent delegated runs for protocol drift (auto-runs ~daily)
/journal	dated recap of the last N days across every project (cached per day)
/brain-retro	fill the journal cache, then run devbrain retro
devbrain brain search	project-first brain search (ranked engine if installed, else offline grep; --global for all-project order)
devbrain dashboard	browser control plane for the queue (view · edit · prioritize · unblock)
devbrain retro	graded monthly report (journal + spend + queue) → retro/<date>.html
devbrain help	every devbrain subcommand

The queue is one markdown file per task, priority-ranked; a task isn't done until its PR merges. Agents without slash commands run the same workflows as skills ($distill, $continue, $reconcile, $audit).

More

• DESIGN.md — architecture, the TODO queue, and the golden rule (never lose the log)
• SECURITY.md — what's captured, where it's stored, who can see it, how to report a vuln
• docs/privacy.md — what an entry looks like, redaction gaps, how to delete/disable/audit your data
• devbrain import — seed the brain from your existing agent transcripts
• make test — run the full suite
• Re-run devbrain install anytime; it only adds what's missing. Tear down with devbrain uninstall (leaves your data untouched).