brains-ai 1.0.2

Local-first control plane and coordination layer for AI coding agents

Brains

A smart local proxy for AI coding agents. Faithful proxy by default — your explicit model picks are never silently rewritten. Opt-in classifier routing sends brains/auto to the cheapest model that can handle the request. One admin key, one audit log, one coordination plane shared across every agent.

⚠️ Active alpha — use with care. This project is under heavy development by a single maintainer. The CLI surface, on-wire contracts, and dashboard internals can change between releases. Pin to a specific version (pipx install brains-ai==0.1.0a12) for anything beyond local experimentation. See Status & stability below.

Why brains

The problem. Every AI coding tool ships its own provider, its own config, its own session memory. Each one defaults to a flagship model for every request — including the trivial ones — so you pay sonnet / o1 rates to "rename this variable." Worse, providers quietly dumbify their flagship tiers under load and then upsell you to the next tier.

What brains does. A local gateway in front of your agents. By default it is a faithful proxy — every request is passed through to the exact provider/model you asked for, with response.model rewritten to the real upstream id (no opaque aliasing). Opt-in classifier routing, gated behind the brains/auto alias, classifies each call (trivial / code_fix / architecture / research / docs_lookup) and routes it to the cheapest provider + model that can handle that class. Anthropic- and OpenAI-compatible endpoints mean Claude Code, Codex, Copilot CLI, Cursor, and aider all work with no code changes — just a base-URL swap.

What you get. Visibility into every dollar your agents spend, the ability to swap providers without touching client code, and one shared coordination plane so your agents share sessions, hand off tasks, and stop stepping on each other.

Install

pipx install brains-ai          # or: uv tool install brains-ai
brains-ai setup                 # init DB + workspace + admin key + wire MCP
brains-ai serve-all             # supervise gateway + dashboard + MCP

To keep it running across reboots without a terminal, install it as a user-level autostart service instead of serve-all:

brains-ai service install       # Windows Task Scheduler / macOS launchd / Linux systemd --user

Prefer not to install Python at all? Use the Docker image instead. Want to hack on brains? Use an editable git checkout — see CONTRIBUTING.md.

Quickstart

1. Install

   pipx install brains-ai
   

2. One-shot bootstrap — setup is idempotent; re-run it any time:

   brains-ai setup
   

   This initializes the DB, registers the current directory as a workspace, provisions an admin key (printed to stderr — record it now), wires brains into every detected agent's MCP config, and prints the next command.

3. Start the stack

   brains-ai serve-all     # gateway :8787, dashboard :9876, MCP :9877
   

   Or run it as an autostart service so it survives reboots and login:

   brains-ai service install   # registers + starts; comes back at every login
   

4. Open the dashboard — http://127.0.0.1:9876/admin and sign in with the admin key.

5. Point a tool at the gateway (so its traffic flows through brains):

   # OpenAI-compatible (Codex, Copilot CLI, aider, Continue, …)
   export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
   export OPENAI_API_KEY=<your-brains-admin-key>
   
   # Claude Code (Anthropic-compatible)
   export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
   export ANTHROPIC_AUTH_TOKEN=<your-brains-admin-key>
   

   …or use the one-shot launcher that sets those for you:

   brains-ai run claude       # launches Claude Code through the gateway
   brains-ai run copilot      # launches GitHub Copilot CLI through the gateway
   

That's it. Your client now sees the gateway as a faithful proxy: ask for claude-sonnet-4.6 and you get claude-sonnet-4.6. Ask for brains/auto and the classifier picks the cheapest model that can handle the request.

Faithful proxy + opt-in routing

Brains was rebuilt around a single contract: never silently rewrite the client's model choice.

Request model	Behaviour
provider/model (e.g. anthropic/claude-sonnet-4.6)	Direct match — routes to the exact upstream, no classifier.
Catalog id (e.g. claude-sonnet-4.6)	Direct match — routes to the upstream id with no silent downgrade.
brains/cheap | brains/default | brains/strong | brains/deep	Tier alias — resolved to the operator-pinned model for that tier.
brains/auto	Classifier runs (only when routing.enabled = true) and picks a model.
Unknown id	404 model_not_found. The classifier never rewrites an explicit request.

response.model is always rewritten back to the actual upstream model that served the request — both on Anthropic and OpenAI surfaces, streaming and non-streaming. Hyphen forms (brains-auto, etc.) remain accepted as legacy aliases.

What's inside

• Smart gateway — Anthropic- and OpenAI-compatible endpoints (/v1/messages, /v1/chat/completions, /v1/responses), faithful-proxy router with toggleable classifier (routing.enabled), multi-provider (Anthropic, OpenAI, GitHub Copilot, Ollama, OpenRouter, LiteLLM, …), namespaced /v1/models.
• Coordination plane — sessions, tasks, handoffs, advisory locks, squads (leader-routed team assignment), autopilots (cron- or webhook-triggered recurring work with per-fire run audit), peer-help RPC, brain-session resume across tool restarts, multi-operator + per-workspace visibility.
• MCP server — every brains capability surfaced as an MCP tool; brains-ai setup (or brains-ai wire) registers it into Claude Code, Codex, Copilot CLI, and Cursor.
• Dashboard + admin — provider health, runtime config (no restarts), audit log, operator presence, runtime overlay editor.
• Launcher — brains-ai run <tool> spawns the target CLI (Claude Code, Copilot CLI, …) with the right ANTHROPIC_* / OPENAI_* env-vars already pointing at your local gateway. Useful for quickly toggling between vanilla CLI and brains.

CLI surface

Command	What it does
brains-ai setup	First-run wizard: init DB → register workspace → ensure admin key → wire MCP → status (--service to also install the autostart service)
brains-ai serve-all	Supervise gateway + dashboard + MCP in one process
brains-ai service install / uninstall / status / start / stop / restart / logs	Run serve-all as a user OS service (Windows Task Scheduler / macOS launchd / Linux systemd --user) — autostart at login + restart on failure
brains-ai serve / brains-ai dashboard / brains-ai mcp	Run a single component
brains-ai features	List optional subsystems (postgres, telegram, slack, otel, …) and install/enable them
brains-ai wire	Register / refresh brains MCP entries in detected agent configs
brains-ai unwire	Remove brains MCP entries from agent configs
brains-ai run <tool>	Spawn claude / copilot with gateway env-vars populated; forwards extra flags
brains-ai admin-key show [--reveal]	Show / rotate the admin key
brains-ai copilot-login / copilot-status / copilot-logout	OAuth device-code flow for github_copilot provider
brains-ai version	Print brains version + schema version + installed extras

Pre-1.0 breaking renames. brains-ai is the single binary. The brains binary, the install verb, and the claude-brains / copilot-brains shims were removed in 0.1.0a8 — use brains-ai, brains-ai features, and brains-ai run claude / brains-ai run copilot respectively. Alpha releases may break renames without a deprecation cycle; every removal is documented in CHANGELOG.md.

Documentation

• Providers & routing — supported providers, config examples, GitHub Copilot OAuth flow, error envelopes
• Agent wiring — brains-ai wire reference, per-tool configs (Claude Code, Cursor, Copilot CLI, Codex)
• Operations — Docker, dev install, upgrades, extras, admin-key management, auth & secrets, dashboard internals, full CLI catalog
• Architecture — runtime flow, components, process topology
• Remote install — reverse-proxy + MCP + multi-machine wiring
• Protocols — wire format for coordination-plane tools
• Security — auth model, leak posture, rotation, redaction
• Decision records — load-bearing design choices
• Roadmap · Changelog

Status & stability

brains is pre-1.0 alpha and developed by a single maintainer in the open.

• Releases are pinned to a single maintainer. All publishing to PyPI and GHCR is gated behind a protected v* tag rule that only the repo owner can trigger. Forks may build their own; the canonical artifact only ships from this repository.
• Backward compatibility is best-effort within an alpha. Pre-1.0 alphas may rename or remove CLI/on-wire surfaces without a deprecation cycle; every breaking change is documented in CHANGELOG.md. Stability tightens at beta.
• main is the supported branch. Older alphas receive no fixes — pin to the latest tag for anything you depend on.
• Status badge above will move to beta once the router contract, dashboard, and admin surface stop changing release-over-release.

Contributing

Issues and well-scoped PRs are welcome — but please open an issue (or use Discussions) before sending a non-trivial PR. See CONTRIBUTING.md and the Code of Conduct. For security issues, follow the private disclosure process in SECURITY.md — do not open a public issue.

License

MIT © mekjr1 and brains contributors.