brains-ai 0.1.0a5

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

Brains

A smart local proxy for AI coding agents. Routes each request to the right-sized model (no more flagship-by-default), proves the dollars saved on the dashboard, and lets every agent share one brain — sessions, tasks, handoffs, recurring jobs.

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. Every request is classified (trivial / code_fix / architecture / research / docs_lookup), routed to the cheapest provider + model that can handle that class, and logged. 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. A real number, on the dashboard, every day: "$X saved this week vs. flagship-default." One admin key. One audit log. One coordination fabric 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 up                       # init + gateway + dashboard + MCP
brains wire                     # register brains into every detected agent

Prefer not to install Python at all? Use the Docker image instead. Want to hack on brains? Use a git checkout. Both paths are documented in Operations.

What's inside

• Smart gateway — Anthropic- and OpenAI-compatible endpoints (/v1/messages, /v1/chat/completions, /v1/responses), classifier-based routing with an on/off toggle (toggle + full Anthropic streaming / tool-use facade land in v1.1 — see Roadmap), per-request savings ledger (v1.1), multi-provider (Anthropic, OpenAI, GitHub Copilot, Ollama, OpenRouter, LiteLLM, …).
• Coordination plane — sessions, tasks, handoffs, advisory locks, recurring jobs, peer-help RPC, brain-session resume across tool restarts, multi-operator + per-workspace visibility.
• MCP server — every brains capability surfaced as an MCP tool; one command (brains 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. Savings panel and provider-first config UI land in v1.1.

Quickstart

1. Install

   pipx install brains-ai
   

2. Start the stack

   brains up      # supervises gateway :8787, dashboard :9876, MCP :9877
   

   On first run, brains generates an admin key and prints it to stderr. View it later with brains admin-key show --reveal.
3. Wire your agents

   brains wire                       # all detected tools (SSE, global)
   brains wire --status              # show what's registered
   

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_API_KEY=<your-brains-admin-key>
   

That's it. Every request is now classified, routed, audited, and shared.

Documentation

• Providers & routing — supported providers, config examples, GitHub Copilot OAuth flow, error envelopes
• Agent wiring — brains wire reference, strict enforcement, per-tool configs (Claude Desktop, 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
• Protocols — wire format for coordination-plane tools
• Decision records — load-bearing design choices
• Roadmap · Changelog · Security

Contributing

See CONTRIBUTING.md and the Code of Conduct. For security issues, follow the disclosure process in SECURITY.md.

License

MIT © mekjr1 and brains contributors.