Codebrain

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

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

# Install dependencies (if needed)
npm install

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

Then choose your packaging:

# 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.

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: leftclick, rightclick, doubleclick, middleclick, mousemove, leftclickdrag, keypress, type, scroll, screenshot, cursorposition, wait, getscreen_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.