Brains

Brains is a local-first control plane for coordinating AI coding agents through shared Workspaces, durable work, local mailboxes, and human approvals.

Agent tools run in isolation: each has its own process, its own history, and a partial view of the work. Brains gives them somewhere shared — so two agents can split work without colliding, a restarted tool can resume real context instead of a transcript, and you keep the decisions that need a human.

Brains is alpha software for one local operator. Everything runs on your machine against a local SQLite database. By default there is no account, no telemetry, and no external service. Optional owner-approved ASK email notifications use your configured SMTP service; see setup and consent.

Install and run

Brains requires Python 3.11 or 3.12.

python -m pip install --user pipx
python -m pipx ensurepath
pipx install brains-ai

Initialize a Workspace, connect your agent tools, and run the service:

cd <project>
brains-ai setup --path .
brains-ai wire
brains-ai serve-all

Open http://127.0.0.1:8787/app. Keep the generated admin key private.

Wiring edits only the managed entry in each tool's configuration. Your formatting and unrelated keys are preserved, and brains-ai unwire restores the file byte for byte.

New here? Start with the guide.

What it does

• Coordination — Workspaces, durable Sessions, tasks, exclusive claims, handoffs, and checkpoints that survive a tool restart
• Local work assignments — create an immutable specification, accept it with an existing Session, and record an outcome with evidence and revision-fenced attempt history; no process launch or checkout management
• Workspace Work tab — author assignments and peer deliberations as the human operator, inspect evidence, request cancellation, and explicitly advance complete protocol rounds
• Communication — durable mailboxes between agent Sessions, proof-bound waiting for unread mail, and peer help requests whose answers must carry evidence
• Knowledge — recorded findings, scoped and searchable, so they are not re-derived
• Human authority — asks and approvals that fail closed where a person is required, with optional, default-off email notifications to the configured owner
• Evidence — a hash-chained audit log you can recompute, and the decision behind every outward effect
• Operations — readiness, backup, restore, and rollback over SQLite

Four harnesses are supported: claude-code, copilot-cli, codex, and opencode.

Current-main documentation covers 89 MCP tools. This branch also provides ten protected operator HTTP endpoints for local assignment and peer-deliberation controls in the existing Workspace Work tab. Human writes use browser-cookie authentication; agents accept work and submit evidence through CLI/MCP. See the operator work guide. This is an unreleased local foundation for part of #42, not completion of cross-process events/replay or transport comparison. Remote runners in #36 and specialist workers in #38 remain deferred to #37 planning. The website describes the pinned 1.5 release and its 74-tool surface.

Model routing, semantic retrieval, and chat bridges are not supported today. The product brief distinguishes planned direction from non-goals and documents retained internal paths without making them supported features.

Planning and contributions

GitHub Issues define work outcomes and acceptance criteria. The Brains Project is the sole source for priority, order, and status; these are not duplicated in Markdown backlogs or external copies. See Contributing before starting work.

Documentation

• Website and release history - published release overview
• Using Brains — the model, and two coordination walkthroughs
• MCP surface — the 89 current-main tools agents can call
• Product brief — what is in scope, and what is not
• Architecture — how the pieces fit together
• Operations — running the service, state, and recovery
• Quality gates — how Brains is validated

Native service installation, platform-specific Claude recovery, and the Docker-isolated full gate are release conditions checked per candidate rather than standing guarantees; see Operations before relying on a background service.

See Contributing, Security, the Code of Conduct, and the MIT License.

The website source lives in site/ on main and is deployed by GitHub Actions. See website maintenance for release synchronization and deployment checks.