# Codebrain

> Multi-agent AI IDE with 244 MCP tools

- **Type:** MCP server
- **Install:** `agentstack add mcp-devmkpro-codebrain`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [devmkpro](https://agentstack.voostack.com/s/devmkpro)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [devmkpro](https://github.com/devmkpro)
- **Source:** https://github.com/devmkpro/codebrain
- **Website:** https://codebrain-lp.vercel.app/

## Install

```sh
agentstack add mcp-devmkpro-codebrain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Codebrain

> Multi-agent AI IDE. Orchestrate Claude, Gemini, MIMO and more — side by side, in real time.

---

## What is Codebrain?

Codebrain is an **Electron desktop app** where multiple AI agents work together in a visible terminal grid.

- **Tiling grid** — auto-organizes 1/2/3/4+ panes
- **Focus mode** — expand any pane to 65% with one click
- **Multi-agent squads** — one orchestrator directs many workers
- **Live task sidebar** — agents update a shared todo list
- **Session map** — visual graph of all agent sessions
- **File editor** — browse and edit without leaving the app
- **Browser automation** — 46 browser MCP tools for web testing
- **Shared memory** — agents share context in real-time via SQLite
- **Swarm coordination** — programmatic worker management and health monitoring
- **Pattern learning** — agents automatically build and reuse project patterns
- **Trajectory tracking** — action sequences with auto-pattern extraction
- **Lifecycle hooks** — EventEmitter-based hooks for spawn, exit, idle events
- **Knowledge graph** — memory relationships, PageRank ranking, TF-IDF similarity search
- **Agent scoring** — multi-factor scoring (capability, load, performance, health, availability)
- **Pipeline coordination** — fan-out/fan-in parallel task distribution and result aggregation
- **Background workers** — 7 persistent maintenance daemons (health, patterns, security, git, learning, cache, swarm)
- **Consensus** — majority/unanimous/weighted voting + automatic leader election
- **Priority MessageBus** — in-memory messaging with 4 priority levels, ack/retry, TTL, metrics
- **Session compaction** — LLM-based summarization when context pressure is high; preserves key decisions and frees tokens
- **Goal/Judge system** — set goals for autonomous agents; independent judge model evaluates if truly satisfied before stopping
- **Checkpoint persistence** — save/restore session state across context limits; 11-section structured checkpoints with validation
- **Cross-session history** — FTS5 search across ALL conversation history with BM25 ranking; filter by kind, tool, time
- **LSP integration** — 12 semantic code navigation tools: goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, callHierarchy, incoming/outgoing calls
- **Text loop recovery** — detects repeated identical text output and injects progressive recovery prompts (mild → strong)
- **Step classification** — classifies agent steps (final/continue/filtered/think-only/invalid/failed) for loop control
- **Max mode** — Best-of-N: run N parallel candidate responses, judge selects the best for higher quality outputs
- **Compose mode** — specs-driven development workflow: plan → execute → review → test → debug → verify → merge
- **Plan agent** — read-only mode for code exploration and solution design before implementation
- **Question tool** — structured user interaction with predefined options; auto-resolve in headless mode
- **Session snapshots** — revert workspace to any previous state; supports revert/unrevert with diff computation
- **Multi-edit** — batch multiple edit operations on a single file in one call
- **Provider-specific prompts** — model-optimized prompt additions per family (Claude, Gemini, GPT, MIMO)
- **Task gate pre-stop** — checks for incomplete tasks before allowing agent to stop; nudges completion
- **244 MCP tools** — pane, browser (CDP + webview), memory, patterns, swarm, hooks, trajectories, files, system, knowledge graph, scoring, pipeline, workers, consensus, skills, LSP (12), session management, goal/judge, checkpoints, history search, compose mode, plan agent, max mode, question tool
- **Skills system** — create, list, install and manage prompt templates scoped to project or globally (`~/.codebrain/skills/`); marketplace with featured skills, tag filters, and one-click install all
- **Voice input** — push-to-talk with Groq Whisper transcription
- **Discord Rich Presence** — shows Codebrain status in your Discord profile; Client ID configurable via Settings
- **Desktop notifications** — native OS notifications when agents complete tasks, receive messages, or builds finish; toggleable per event type in Settings
- **Session export** — export any session as Markdown or JSON with a native save dialog
- **Session history** — SQLite-backed history panel; auto-saves every terminal session with preview and delete
- **Token cost tracking** — real-time cost per session/model/agent with budget alerts; supports 140+ models (Claude, Gemini, MIMO, Codex, OpenRouter, DeepSeek, Grok and more)
- **Auto-update** — background update checks with Windows registry repair

---

## Quick Start

```bash
git clone https://gitlab.com/maikeofc18/codebrain.git
cd codebrain
npm install
npm run dev
```

That's it. Hot reload is instant.

### What happens in dev mode

- **Renderer** — HMR automatic (change .tsx, reloads instantly)
- **Main** — Restarts Electron on save to `electron/main/**`
- **Preload** — Rebuilt automatically on save

### Useful shortcuts in the app

| Shortcut | Action |
|----------|--------|
| `F12` | Toggle DevTools (dev mode) |
| `Ctrl+R` | Blocked in production (prevents accidental reload) |
| `Ctrl+Q` / `Cmd+Q` | Quit app |
| `Ctrl+W` / `Cmd+W` | Close window |
| `Ctrl+M` / `Cmd+M` | Minimize window |
| `Escape` | Minimize window |

---

## Build Executable

```bash
# Install dependencies (if needed)
npm install

# Generate releases data + bundle stdio MCP + Vite build
npm run build
```

Then choose your packaging:

```bash
# Windows — Portable ZIP (no admin needed, recommended)
npm run pack:win

# Windows — NSIS installer (.exe, requires admin or Developer Mode)
npm run dist:win:nsis

# Windows — Full pipeline (prebuild native + bundle + build + package)
npm run dist:win

# macOS
npm run dist:mac

# Linux (AppImage + .deb)
npm run dist:linux
```

Output goes to `dist/`.

### Troubleshooting build errors

If NSIS fails with symlink errors, enable **Developer Mode**:
`Settings > System > For Developers` or run the terminal as Administrator.

---

## Releases

Download the latest from [GitLab Releases](https://gitlab.com/maikeofc18/codebrain/-/releases).

Available for:
- Windows x64 (NSIS installer + portable ZIP)
- Linux x64 (AppImage + .deb)

---

## Stack

| Layer | Tech |
|-------|------|
| Framework | React 19 + TypeScript |
| Styling | Tailwind CSS v4 |
| State | Zustand v5 |
| Terminal | xterm.js v6 |
| Animation | Motion (Framer) |
| Icons | lucide-react |
| Font | JetBrains Mono |
| MCP | @modelcontextprotocol/sdk |
| CI/CD | GitLab CI |

---

## Providers (API Keys)

Click the account icon → **Providers** → **+ Add Provider**.

| Role | Provider | Model |
|------|----------|-------|
| Orchestrator | Claude / Anthropic | claude-sonnet-4-6 |
| Workers | Gemini API | gemini-3.1-pro-preview |

---

## MCP Tools

Agents get these tools automatically:

### Core (pane management)

| Tool | What it does |
|------|-------------|
| `pane_spawn` | Open a new agent terminal |
| `pane_write` | Send text to a pane |
| `pane_read` | Read pane output |
| `pane_wait_idle` | Wait until agent finishes |
| `pane_send_message` | Message another agent |
| `pane_read_messages` | Read your inbox |
| `pane_list` | List active panes |
| `pane_set_role` | Assign worker/orchestrator role |
| `todo_manager` | Manage the task sidebar |

### Browser automation (53 tools)

All tools work in **dual mode**: native Chrome via CDP (auto-detected on port 9222) or embedded Electron webview (fallback).

| Tool | What it does |
|------|-------------|
| `browser_guide` | MANDATORY — read before any browser tool |
| `browser_mode` | Current mode: CDP (native Chrome) or webview (embedded) |
| **Navigation** | |
| `browser_navigate` | Go to a URL |
| `browser_open` | Open new browser pane |
| `browser_back` / `browser_forward` | History navigation |
| `browser_reload` | Reload page |
| **DOM reading** | |
| `browser_get_html` | Get raw HTML |
| `browser_get_text` | Get visible text |
| `browser_get_accessibility_tree` | Semantic tree (roles, labels, bounds) |
| `browser_find_by_text` | Find element by visible text |
| `browser_find` | Natural language element search (CDP-only) |
| `browser_get_element_info` | Full element info (bounds, attributes, role) |
| `browser_get_url` | Current URL + title |
| `browser_page_summary` | URL, text, links, inputs, buttons in one call |
| **DOM interaction** | |
| `browser_click` | Click element by CSS selector |
| `browser_click_text` | Find + click by visible text |
| `browser_fill` | Fill input/textarea |
| `browser_fill_form` | Fill multiple fields at once |
| `browser_select` | Select dropdown option |
| `browser_check` | Check/uncheck checkbox |
| `browser_clear` | Clear input field |
| `browser_focus` | Focus element |
| `browser_hover` | Hover element (triggers tooltips) |
| **Coordinate interaction** | |
| `browser_click_at` | Click at exact (x, y) |
| `browser_hover_at` | Hover at exact (x, y) |
| `browser_drag` | Drag from (x1,y1) to (x2,y2) |
| `browser_scroll` | Scroll page or element |
| **Keyboard** | |
| `browser_type` | Type text character by character |
| `browser_key` | Press single key (Enter, Escape, Tab…) |
| `browser_shortcut` | Keyboard shortcut (Ctrl+A, Ctrl+Shift+I…) |
| **Computer (CDP-only)** | |
| `browser_computer` | Mouse/keyboard/screen actions (13 action types: left_click, right_click, double_click, middle_click, mouse_move, left_click_drag, key_press, type, scroll, screenshot, cursor_position, wait, get_screen_size) |
| **Tabs (CDP-only)** | |
| `browser_tabs_list` | List all open Chrome tabs |
| `browser_tabs_create` | Create a new tab |
| `browser_tabs_close` | Close a tab by ID |
| **Batch (CDP-only)** | |
| `browser_batch` | Execute multiple browser actions in a single roundtrip |
| **Wait / assertions** | |
| `browser_wait_for` | Wait for element to appear |
| `browser_wait_for_text` | Wait for text to appear |
| `browser_wait_for_url` | Wait for URL pattern |
| `browser_wait_for_load` | Wait for network idle |
| **Screenshots** | |
| `browser_screenshot` | Capture viewport (returns text description) |
| `browser_screenshot_element` | Capture specific element |
| `browser_annotate` | Draw boxes/arrows/labels on screenshot |
| **Console & network** | |
| `browser_console_log` | Read console entries (log/warn/error) |
| `browser_clear_console` | Clear console log |
| `browser_network_log` | Read network requests (fetch, XHR, WebSocket) |
| `browser_network_wait` | Wait for specific request |
| `browser_clear_network` | Clear network log |
| **Advanced** | |
| `browser_eval` | Execute JavaScript in page context |

### Shared Memory (6 tools)

| Tool | What it does |
|------|-------------|
| `memory_write` | Save context (type, key, content, tags) to shared SQLite memory |
| `memory_read` | Read specific memory by id or key |
| `memory_search` | Search memories by keyword, type, or tags |
| `memory_list` | List memories with filters (type, agent, workspace) |
| `memory_delete` | Delete a memory entry |
| `memory_stats` | Memory usage statistics (count by type, total size) |

### Knowledge Graph (3 tools)

| Tool | What it does |
|------|-------------|
| `memory_graph` | Get a memory node + neighbors with edge types (reference, similar, temporal, co_accessed) |
| `memory_rank` | PageRank scores for all memories — find the most important/central ones |
| `memory_similar` | Find similar memories using TF-IDF cosine similarity |

### Pattern Learning (4 tools)

| Tool | What it does |
|------|-------------|
| `pattern_write` | Save a learned pattern (type, description, quality score) |
| `pattern_list` | List patterns ordered by quality score |
| `pattern_update` | Update pattern quality score after successful use |
| `pattern_delete` | Delete a pattern |

### Swarm Coordination (6 tools)

| Tool | What it does |
|------|-------------|
| `swarm_status` | Swarm health: active workers, roles, topology |
| `swarm_broadcast` | Broadcast message to all workers |
| `swarm_assign_task` | Assign task to specific worker via message |
| `swarm_worker_health` | Health check on individual worker |
| `swarm_respawn` | Respawn a crashed worker |
| `swarm_set_topology` | Set topology: hierarchical, mesh, centralized |

### Agent Scoring (1 tool)

| Tool | What it does |
|------|-------------|
| `swarm_score_agents` | Multi-factor scoring: capability(30%), load(20%), performance(25%), health(15%), availability(10%) |

### Pipeline Coordination (4 tools)

| Tool | What it does |
|------|-------------|
| `swarm_fan_out` | Distribute N tasks to workers in parallel (round-robin) |
| `swarm_fan_in` | Collect + aggregate results (merge, vote, or best-agent) |
| `swarm_pipeline` | Chain sequential tasks where each step feeds the next |
| `swarm_pipeline_status` | Check pipeline execution status |

### Consensus (4 tools)

| Tool | What it does |
|------|-------------|
| `swarm_vote` | Start a vote: majority (>50%), unanimous (100%), or weighted (by agent score) |
| `swarm_cast_vote` | Cast a vote in an active session |
| `swarm_elect_leader` | Auto-elect leader by capability score |
| `swarm_consensus_status` | Current leader, active votes, recent results |

### Background Workers (6 tools)

| Tool | What it does |
|------|-------------|
| `worker_start` | Start a daemon (health, patterns, security, git, learning, cache, swarm) |
| `worker_stop` | Stop a daemon |
| `worker_status` | All daemons' status, last run, metrics |
| `worker_alerts` | Recent system alerts from daemons |
| `worker_start_all` | Start all 7 daemons |
| `worker_stop_all` | Stop all daemons |

### MessageBus (1 tool)

| Tool | What it does |
|------|-------------|
| `pane_bus_metrics` | Messages/sec, avg latency, queue depths, ack timeouts |

### Trajectory Tracking (8 tools)

| Tool | What it does |
|------|-------------|
| `trajectory_record` | Start recording a new action trajectory |
| `trajectory_add_step` | Add a step (tool call + result) to trajectory |
| `trajectory_update` | Update trajectory outcome and details |
| `trajectory_list` | List trajectories with filters |
| `trajectory_get` | Get full trajectory by id |
| `trajectory_stats` | Trajectory statistics (success rate, avg duration) |
| `trajectory_extract_patterns` | Auto-extract patterns from successful trajectories |
| `trajectory_delete` | Delete a trajectory |

### Lifecycle Hooks (3 tools)

| Tool | What it does |
|------|-------------|
| `hooks_status` | Registered hooks and recent event stats |
| `hooks_log` | Recent hook events (spawn, exit, idle, message) |
| `hooks_fire` | Manually fire a hook event for testing |

### File Tools (3 tools)

| Tool | What it does |
|------|-------------|
| `file_read` | Read file from workspace |
| `file_write` | Write file to workspace |
| `file_search` | Search files by pattern or content |

### System Tools (2 tools)

| Tool | What it does |
|------|-------------|
| `system_info` | System info (OS, RAM, CPU, app version) |
| `system_diagnostics` | Full diagnostics (pane health, MCP status, providers) |

### Worker Dispatch (3 tools)

| Tool | What it does |
|------|-------------|
| `worker_detect` | Scan text for dispatch triggers (optimize, audit, etc) |
| `worker_dispatch` | Spawn background worker for detected trigger |
| `worker_list_bg` | List active background workers |

### Skills (6 tools)

| Tool | What it does |
|------|-------------|
| `skill_list` | List installed skills — global (`~/.codebrain/skills/`) and/or project (`.codebrain/skills/`) |
| `skill_get` | Get full skill content: manifest + prompt.md |
| `skill_create` | Create a new skill locally with prompt content, scope and tags |
| `skill_delete` | Delete a skill by id and scope |
| `skill_install` | Install a skill from the GitLab registry to `~/.codebrain/skills/` |
| `skill_uninstall` | Remove an installed skill |

**Total: 177 MCP tools**

---

## Project Structure

```
codebrain/
├── src/                    React r

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [devmkpro](https://github.com/devmkpro)
- **Source:** [devmkpro/codebrain](https://github.com/devmkpro/codebrain)
- **License:** MIT
- **Homepage:** https://codebrain-lp.vercel.app/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-devmkpro-codebrain
- Seller: https://agentstack.voostack.com/s/devmkpro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.