CodeConductor

Multi-agent AI coordination protocol for VS Code.

CodeConductor is a VS Code extension and MCP server that lets multiple AI agents collaborate on a codebase safely — with file locking, structured handoffs, health monitoring, token budgets, and a full agent template catalog.

Quick Start In 60 Seconds

npm install
npm run init
npm run demo

npm run init generates local config for the current repo. npm run demo runs a two-agent MCP handoff flow end to end.

Project Links

• Notion hub: https://www.notion.so/32bcddcb424a81ca94fed8a0395be0b8
• Linear project: https://linear.app/teambotics/project/codeconductor-787ab03f81b6
• Linear current-state doc: https://linear.app/teambotics/document/codeconductor-current-state-and-tracking-hub-17c4ebef3fe9
• Repo-maintained link map: docs/PROJECT-LINKS.md

Use Notion for the broader project narrative and design context. Use Linear for active execution tracking and release follow-up work.

Features

• File Locking — Exclusive and shared locks prevent concurrent write conflicts between agents
• Handoff Workflows — Structured work transfer between agents with priority, chaining, and model-tier recommendations
• Health Monitoring — Real-time session health checks with EventBus-driven alerts
• Token Budget Tracking — Per-session usage recording with model tier recommendations (worker vs lead)
• AST Context Extraction — Tree-sitter powered code structure snapshots delivered to agents on demand
• Agent Catalog — 100+ agent templates across 10 categories (design, engineering, marketing, product, project-management, spatial-computing, specialized, strategy, support, testing)
• Glassmorphism Dashboard — Sidebar and full-editor panel with animated view switcher, session cards, handoff kanban, and file lock visualization
• MCP-Native — Exposes 24 cc_* tools consumable by any MCP client (Claude Code, Codex, GitHub Copilot Agent, etc.)

Architecture

┌─────────────────────────────────────────┐
│          VS Code Extension              │
│  (tree-view, commands, dashboard, UI)   │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│              MCP Server                 │
│  (24 cc_* tools, stdin/stdout transport)│
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│            Core Library                 │
│  sessions · locks · handoffs · health   │
│  agent-catalog · token-budget · ast     │
│  context-capsule · git · store (SQLite) │
└─────────────────────────────────────────┘

All state is persisted in an in-memory SQLite database (sql.js/WASM). An internal EventBus propagates state changes to the extension UI in real time.

Installation

From VSIX (recommended)

code --install-extension codeconductor-0.1.0.vsix

From Source

git clone https://github.com/nickhilster/CodeConductor.git
cd CodeConductor
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

See docs/INSTALLATION.md for full details including marketplace and MCP-only setups.

Quick Start

1. Configure MCP

Create .mcp.json in your project root:

{
  "mcpServers": {
    "codeconductor": {
      "command": "npx",
      "args": ["codeconductor-server"],
      "env": {}
    }
  }
}

2. (Optional) Customize Repo Preferences

Create .codeconductor.json in your project root:

{
  "agentCoordination": {
    "defaultModel": "gpt-4",
    "budget": 120000
  },
  "tools": {
    "fileLocking": true,
    "handoffWorkflows": true
  }
}

3. Start an Agent Session

cc_start_session
  agent_id: "engineer-1"
  goal: "Implement OAuth2 login flow"

4. Lock Files Before Writing

cc_lock_files
  session_id: "<session_id>"
  agent_id: "engineer-1"
  files: ["src/auth/login.ts"]
  lock_mode: "exclusive"

5. Handoff Completed Work

cc_create_handoff
  from_agent: "engineer-1"
  summary: "OAuth2 login implemented. Needs review."
  to_agents: ["reviewer-1"]
  priority: "high"

See docs/QUICKSTART.md for a step-by-step tutorial.

MCP Tool Reference

All 24 tools are prefixed with cc_. See docs/API.md for full parameter documentation.

VS Code Commands

Documentation

Development

npm install          # Install dependencies
npm run compile      # Build extension (esbuild → out/extension.js)
npm run test:ci      # Run all 543 tests
npm run lint         # ESLint
npm run package:vsix # Package VSIX

Press F5 in VS Code to launch the Extension Development Host.

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and the pull request process.

Security

To report a vulnerability, see SECURITY.md.

License

MIT — Copyright © Teambotics. See LICENSE for details.