Brains

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

Current maturity: Brains is an alpha release. The normal product is the Workspace-first coordination, governance, operations, access/configuration, GitHub-linkage, and local-lookup surface. Withdrawn implementations are not product claims even where containment removal from current source remains open. Live deployment and external provider behavior are not certified by repository evidence.

Brains is the canonical product and repository identity. It is distributed as brains-ai, uses the brains Python namespace, brains_ MCP prefix, ~/.brains state directory, brains-spa frontend package, and Brains browser identity.

Install

Brains requires Python 3.11 or 3.12. Install the CLI in an isolated environment:

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

Initialize Brains for the project you want it to coordinate and install the supervised user service:

cd <project>
brains-ai setup --path . --service

The service starts without a terminal window, restarts on failure, and starts again at login. Verify it with brains-ai service status, then open http://127.0.0.1:8787/app. The setup command prints the generated admin-key location; reveal it only when needed with brains-ai admin-key show --reveal.

Use brains-ai serve-all only when foreground logs are useful for diagnosis or development. Upgrade an existing isolated installation with pipx upgrade brains-ai.

Canonical documentation

• Product brief
• Feature contract
• User outcome specification
• Personas and journeys
• Traceability
• Architecture
• Operations
• Quality gates
• Backlog registry
• Active feature backlog
• Experimental feature backlog

Repository guidance

• Contributing
• Security
• Agent instructions
• Code of Conduct
• MIT License