Cerebro MCP

The brain that builds.

v2.1.0 — All 28 tools fully implemented. Zero stubs. Production-ready.

Universal AI orchestrator — MCP for tools, A2A for agents. Chat thinks, agents specialize, CLI codes. One conversation, working software. No terminal required.

First orchestrator to unify MCP + A2A. Both Linux Foundation standards. Tools speak MCP. Agents speak A2A. Cerebro orchestrates both.

Live Demo · Architecture · API Reference · Agent Guide

---

The Problem

You have a great idea. You can describe it perfectly. But you can't build it because you don't know how to code.

Claude Chat can plan and brainstorm but can't write files. Claude Code CLI can build software but requires a terminal. Existing orchestrators target developers. There's nothing for the 99% of people who think in ideas, not code.

The Solution

Cerebro MCP makes Claude Chat the brain that controls everything. You describe what you want in plain English. Cerebro decomposes your idea, routes tasks to specialist agents, spawns CLI workers, and reports back in language you understand.

You: "Build me a landing page for my coffee shop with online ordering"

Cerebro: Breaking this into tasks...
  → Designer agent: Creating layout with hero, menu grid, order CTA
  → Coder agent: Building responsive HTML/CSS with cart functionality  
  → QA agent: All 12 tests passing. Lighthouse score: 96.

Your landing page is ready at localhost:3000.

You never see a terminal. You never write code. You just talk.

Quick Start

npx @synvoya/cerebro-mcp

Then add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "cerebro": {
      "command": "npx",
      "args": ["@synvoya/cerebro-mcp"]
    }
  }
}

Restart Claude Desktop. Cerebro's 30 tools are now available in Chat.

Just Talk — Zero Setup Mode

Don't want to learn tools? Just use quick_task:

You: "Build me a portfolio website in ~/Projects/my-portfolio"

Cerebro: Auto-creating session... picking Claude Code + Sonnet...
  → Terminal opens, Claude Code starts building
  → Task completed! Files saved to ~/Projects/my-portfolio

No sessions to create. No agents to configure. Just describe what you want and where to save it.

What's New

v2.3.0 — Shell Safety + Execution Modes (April 2026)

• Interactive Mode (new default) — See Claude Code's live thinking, tool calls, and file operations in the terminal. No more blind waits.
• Quiet Mode — Say "quiet mode" to show only task + result. Previous default behavior.
• Shell Escaping Fix — Task descriptions with backticks, quotes, and special characters no longer break terminals.
• executionMode preference via configure_model — "show thinking", "hide execution", "interactive", "quiet".

v2.2.0 — Context Watcher (April 2026)

• Context Watcher — start_context_watcher opens a persistent terminal showing real-time token usage, progress bar, and handover recommendations. Off by default.
• Terminal Preferences — Global auto-close, no-terminal, and watcher toggles via configure_model.
• 30 MCP Tools — Two new tools: start_context_watcher, stop_context_watcher.

v2.1.0 — All Tools Working (April 2026)

Every single one of Cerebro's 28 tools now works for real. No stubs, no placeholders, no "coming soon."

• Code Review — review_code now runs a real code review via CLI. Get quality, security, and best practice feedback on your project.
• Build & Test — run_build and run_tests detect your build system and run it. Works with npm, Python, Go, Rust, and more.
• Agent Marketplace — install_agent_pack loads pre-built agent teams from starter kits. Try web-app, api-service, or content-site.
• Vision Pipeline — Upload a screenshot to Chat. Chat sees it, describes it, and Cerebro fixes or builds from it. No API key needed — Chat IS the vision layer.
• Context Health — get_context_health tracks real token usage per session. Warns you at 60%, suggests handover at 80%.

Note: get_context_health tracks Cerebro session context (task count and estimated token usage within a Cerebro session), not the Chat conversation window. For Chat context, Claude will naturally suggest starting a new conversation when the window gets full. Real-time Chat context tracking is planned for v3.0.

• Token Persistence — Handover tokens now survive server restarts. Your session tokens stay valid across reboots.
• Security — AppleScript injection prevention in terminal titles. Token secrets stored with owner-only file permissions.

v2.0.0 — Major Feature Release (April 2026)

• Quick Task — Just say what you want. No sessions, no agents, no config. Cerebro figures it out.
• Project Reader — Cerebro reads your folder structure and code before making changes. No blind edits.
• Multi-Provider CLI — Use Claude Code, OpenAI Codex, or Aider. Switch providers with one sentence.
• Visible Terminal Windows — Watch your AI work in real Terminal windows. See every command as it runs.
• Auto-Close Terminal — Terminal stays open by default so you can review. Pass autoCloseTerminal: true to close automatically.
• Smart Model Routing — Cerebro uses Sonnet by default. Say "use Opus" to switch. Codex automatically uses its own models (gpt-5.4).
• Provider & Model in Results — Chat always tells you which agent, provider, and model completed your task.
• Auto Git Init for Codex — Codex requires a git repo. Cerebro auto-initializes one if needed.

What Makes Cerebro Different

	Remote Control	Other Orchestrators	Cerebro MCP
For	Developers	Developers	Non-coders
Direction	User → CLI	Dev → agents	Chat → everything
Protocols	MCP only	Custom	MCP + A2A
Agent creation	N/A	Config files	Just talk
Context rot	Not addressed	Manual clear	Fresh per task
External agents	N/A	N/A	Any A2A agent joins
Session continuity	Single session	N/A	Signed tokens
CLI providers	Claude Code only	Single provider	Multi-provider
Zero setup	N/A	Config required	Just talk

Architecture

User (non-coder)
  │ Natural language, images
  ▼
Claude Chat (brain)
  │ Plans, decomposes, delegates
  ▼
Cerebro MCP Server (orchestrator)
  │ MCP for tools │ A2A for agents
  ├─────────┼─────────┤
  ▼         ▼         ▼
CLI      Agent      External
Workers  Swarm      MCPs
  │         │         │
  ▼         ▼         ▼
Agent Marketplace + A2A Interop
  │
  ▼
Working Product

Dual Protocol

Cerebro is the first orchestrator to implement both standards:

• MCP (Model Context Protocol) — how Cerebro talks to tools. CLI, databases, GitHub, Slack.
• A2A (Agent-to-Agent Protocol, v0.3) — how agents talk to each other. Internal delegation and external interop.

Both protocols live under the Linux Foundation.

Features

Agent Swarm — Build Your AI Team by Talking

Create specialist agents with natural language. No config files, no YAML.

You: "Add a marketing agent that writes social media posts in a casual tone"
Cerebro: Marketing agent created and added to your swarm.

You: "Write a launch tweet for the coffee shop"
Cerebro → Marketing agent: "your morning just got an upgrade. order your 
  favorite latte from the couch and pick it up hot."

Agents persist across sessions. They learn your preferences. They delegate to each other via A2A.

Fresh Context — Zero Memory Rot

Every agent call gets a fresh context window. Agent definitions and learned preferences persist, but working context is wiped after each task. No stale reasoning accumulates. Ever.

Multi-Provider CLI — Choose Your Tools

Cerebro isn't locked to a single CLI. Route different task types to different providers using natural language.

You: "Use Claude Code for coding tasks and Codex for code review"
Cerebro: Worker routing updated.
  → Coding tasks → Claude Code CLI
  → Code review → OpenAI Codex CLI

You: "What CLI tools do I have installed?"
Cerebro: Detected providers:
  ✓ Claude Code CLI (authenticated)
  ✓ Codex CLI v0.118.0 (authenticated)
  ✗ Aider (not installed)

Supported providers: Claude Code, OpenAI Codex, Aider, and any generic shell command. Cerebro auto-detects installed tools and intelligently routes tasks based on agent name, description, and routing rules.

A2A Interop — Your Swarm Has No Walls

Every Cerebro agent is automatically A2A-compliant. They publish Agent Cards at /.well-known/agent-card.json. External A2A agents from Salesforce, SAP, LangChain, CrewAI — anything A2A-compliant — can join your swarm.

You: "Connect the Salesforce agent and update our CRM"
Cerebro: Discovering agent via Agent Card... connected.
  → Salesforce agent: Campaign created, catalog updated.

Agent Marketplace — Three Tiers

1. Anthropic Skills — Curated templates from Anthropic's open-source repo (Apache 2.0)
2. Community agents — Shared by users, reviewed, tagged
3. Your agents — Created by you, private by default, optionally shareable

Session Tokens — Survive Chat Handovers

When your chat hits context limits, Cerebro generates a signed handover token. Paste it in a new chat and continue exactly where you left off. Sessions, agents, task history — everything transfers.

Terminal and Watcher Configuration

Control terminal behavior with natural language via configure_model:

User says	Preference	Effect
"auto close terminals"	autoCloseTerminal: true	Worker terminals close after task completes
"keep terminals open"	autoCloseTerminal: false	Terminals stay open for review (default)
"no terminal" / "background mode"	spawnMode: background	CLI tasks run silently, no Terminal windows
"show terminal" / "visible mode"	spawnMode: visible	Tasks open visible Terminal windows (default)
"interactive" / "show thinking"	executionMode: interactive	See Claude Code thinking and tool calls live in terminal (default)
"quiet" / "hide execution"	executionMode: quiet	Terminal shows only task description and final result
"no watcher" / "disable watcher"	watcherAutoStart: false	Context Watcher will not auto-start (default)
"enable watcher"	watcherAutoStart: true	Context Watcher auto-starts

Combine freely. Example scenarios:

Scenario	Config	Behavior
Full visibility (default)	none needed	Each task opens a Terminal. Watcher available. Terminals stay open
Fire and forget	auto close terminals	Terminals open then close when done
Silent mode	no terminal	Everything runs in background. Results in Chat
Headless / VPS	background mode, disable watcher	No GUI needed. All results via MCP
Visible + watcher	auto close terminals, enable watcher	Task terminals flash open/close. Watcher stays open
Quiet terminals	quiet mode	Terminals open but only show task + result

All preferences persist for the session. Change anytime via configure_model.

Starter Kits

Drop a .cerebro/agents.json in any project and agents auto-spawn on session start.

Built-in kits: web-app (Coder + Designer + QA), api-service (Coder + QA + DevOps), content-site (Designer + Coder + Marketing).

Live Dashboard

Real-time agent status with heartbeats, task broadcasting, and conversation threading. See your AI team working like a project management board.

Vision Pipeline — Screenshot to Fix

Upload a screenshot, mockup, or error message to Chat. Chat (Claude) sees and interprets the image, then orchestrates Cerebro to act on it. No API key needed — Chat IS the vision layer.

You: [uploads screenshot of broken nav bar]
Chat: "I can see the nav overlaps the hero section on mobile. The z-index needs fixing."
→ Cerebro calls implement_from_image
→ Coder agent patches the CSS
→ "Fixed! Nav now layers correctly on all screen sizes."

This works because Claude Chat has built-in vision. When you paste an image, Chat describes what it sees and translates that into instructions for Cerebro's CLI workers.

Visible Terminals — Watch Your AI Work

Every task opens a real Terminal window so you can see exactly what's happening. The terminal shows the agent name, provider, model, and live CLI output as it runs. After completion, the terminal stays open for you to review.

Want the terminal to close automatically? Pass autoCloseTerminal: true when delegating tasks.

Note: Claude Code runs in --print mode which shows a summary of what was built. Codex shows more detailed output including the exact commands it runs. The full output is always captured and sent back to Chat regardless of what the terminal displays.

Project Reader — AI Understands Your Code

Before making changes, Cerebro can read your entire project structure and file contents. The AI understands your codebase before touching it — no blind edits.

You: "Read my project and explain the architecture"
Cerebro: Scanning ~/Projects/my-app...
  → 42 files across 8 directories
  → TypeScript project with React frontend and Express backend...

30 MCP Tools

Session Management

Tool	What it does
create_session	Start a new project workspace. Tell it where to save files.
resume_session	Continue where you left off using a handover token.
pause_session	Park your session for later — everything is saved.
end_session	Finish and archive a session with all task history.
list_sessions	See all your active, paused, and recent sessions.

Task Execution

Tool	What it does
quick_task	The easiest way to use Cerebro. Just say what you want — auto-creates session, picks provider, and builds. No setup needed.
execute_task	Run a task within an existing session. Auto-routes to the best agent.
read_project	Read your project's folder structure and file contents so the AI understands your codebase.
get_status	Check what's happening — see progress on all tasks.
review_code	Get a human-friendly explanation of code changes.
run_build	Trigger a build and see the results.
run_tests	Run your test suite and get a summary.

Agent Swarm

Tool	What it does
create_agent	Create a specialist agent by describing what it should do. "Add a QA agent that reviews code for security issues."
list_agents	See all agents in your swarm with their status.
update_agent	Change an agent's persona, skills, or preferences.
remove_agent	Remove an agent from your swarm.
get_agent_status	Check what a specific agent is working on.
install_agent_pack	Install a pre-built team: web-app, api-service, or content-site.
delegate_to_agent	Send a task directly to a specific agent. Returns provider, model, and results.

Vision (Image Pipeline)

Tool	What it does
analyze_image	Paste a screenshot or mockup — Cerebro interprets it and suggests actions.
implement_from_image	Turn a screenshot or design into working code.
compare_screenshots	Visual diff between expected and actual — find what changed.

Session Continuity

Tool	What it does
prepare_handover	Generate a signed token to continue in a new chat window.
validate_token	Check if a handover token is still valid.
get_context_health	See how much context window remains before you need a handover.

Context Watcher

Tool	What it does
start_context_watcher	Start real-time token tracking with a live terminal dashboard.
stop_context_watcher	Stop the context watcher and close the dashboard.

What the Context Watcher Tracks

The Context Watcher estimates token usage — it does not read Claude's actual context window.

What	Tracked?	How
Cerebro MCP tool calls (main Chat)	Yes	Counts each tool call, applies per-tool token estimates
Conversation overhead (system prompt, tool defs)	Yes	Fixed 15k token base estimate
Per-turn conversation cost	Yes	~1500 tokens per tool call turn
What happens inside spawned CLI terminals	No	Each terminal is an independent Claude Code session
Claude's real context window size	No	No API available — all values are estimates
Other MCP server calls	No	Only Cerebro tools are tracked

The watcher answers: "How full is my main Chat based on Cerebro tool call volume?" — which is what matters for knowing when to handover. It is off by default. Start it with start_context_watcher when you want visibility.

Worker Configuration

Tool	What it does
configure_workers	Route tasks to different CLI providers. "Use Codex for QA tasks."
detect_providers	See which CLI tools are installed on your system.
configure_model	Set the AI model and effort level. "Use Opus with high effort."

CLI Provider Setup

Claude Code (recommended)

npm install -g @anthropic-ai/claude-code
claude-code auth

OpenAI Codex

npm install -g @openai/codex
codex auth

Then in Chat:

You: "Use Codex for code review tasks"
Cerebro: Routing updated — code review tasks → Codex CLI.

Aider

pip install aider-chat

Cerebro auto-detects all installed providers via detect_providers.

Note: Cerebro automatically handles model compatibility between providers. If you configure Sonnet as your model, Cerebro will use it for Claude Code but skip it for Codex (which uses its own OpenAI models like gpt-5.4). No manual configuration needed.

Project Structure

cerebro-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # 28 MCP tools registered
│   ├── session/              # Session lifecycle + SQLite store
│   ├── router/               # Task routing + decomposition
│   ├── workers/              # CLI providers, terminal spawner,
│   │                         # model config, pool, Cowork (V2), MCP relay
│   ├── agents/               # Swarm, runner, confidence, delegation,
│   │                         # memory, marketplace, heartbeat, threading
│   ├── a2a/                  # A2A server, client, Agent Cards, lifecycle
│   ├── vision/               # Image relay + interpreter
│   ├── context-watcher/      # Token tracking + terminal dashboard
│   ├── handover/             # Engine, context monitor, directory
│   ├── notifications/        # Webhooks + push alerts
│   ├── dashboard/            # Agent status dashboard
│   ├── security/             # HMAC-SHA256 crypto
│   ├── reporter/             # CLI output → human-friendly summaries
│   └── types/                # TypeScript type definitions
├── agents/                   # Built-in agent templates
├── starter-kits/             # Shareable .cerebro/ configs
└── tests/                    # Vitest test suite

Development

git clone https://github.com/Synvoya/cerebro-mcp.git
cd cerebro-mcp
npm install
npm run build
npm test

Current stats: v2.1.0 · 69 files · ~6,500 lines of TypeScript · 28 MCP tools (all fully implemented) · 40/40 tests passing

Roadmap

• [x] MCP server with 28 tools — all fully implemented (v2.1.0)
• [x] Session management with signed tokens
• [x] Agent swarm with conversation-based CRUD
• [x] A2A protocol for agent-to-agent communication
• [x] Agent marketplace (3-tier)
• [x] Heartbeat presence + task broadcasting
• [x] Message threading between agents
• [x] Auto-registration via .cerebro/agents.json
• [x] Starter kits (web-app, api-service, content-site)
• [x] Claude Code CLI integration (subprocess management)
• [x] Multi-provider CLI (Claude Code, Codex, Aider, generic shell)
• [x] Quick task — zero-setup execution via natural language
• [x] Project reader — AI reads your codebase before making changes
• [x] Visible terminal spawner (branded agent windows)
• [x] Model and effort configuration via natural language
• [ ] Cowork integration (pending Anthropic API)
• [ ] Agent dashboard web UI
• [ ] Remote CLI workers (VPS/cloud)
• [ ] Context Watcher — real-time Chat context window tracking with live terminal dashboard (v3.0)
• [ ] Community agent repository

Contributing

See CONTRIBUTING.md for guidelines. No CLA required — contributions are licensed under Apache 2.0.

License

Apache 2.0 — see LICENSE. Copyright (c) 2026 Synvoya.

Links

• Website: cerebro.synvoya.com
• npm: @synvoya/cerebro-mcp
• GitHub: Synvoya/cerebro-mcp
• Company: Synvoya

---

Built with passion by Hibi and the Synvoya team. The brain that builds.