# mcp-codex-teams

[![npm version](https://img.shields.io/npm/v/mcp-codex-teams.svg)](https://www.npmjs.com/package/mcp-codex-teams)
[![CI](https://github.com/yigitkonur/mcp-codex-teams/actions/workflows/ci.yml/badge.svg)](https://github.com/yigitkonur/mcp-codex-teams/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-codex-teams.svg)](https://www.npmjs.com/package/mcp-codex-teams)

An MCP server that lets AI agents orchestrate multi-agent teams on top of [OpenAI Codex CLI](https://github.com/openai/codex). Spawn teammates, assign tasks, coordinate via inboxes — all through 12 standard MCP tools that mirror the Claude Code agent-teams protocol.

Each team gets a shared Git worktree so teammates work on the same codebase without merge conflicts. Tasks form a dependency graph with cycle detection. Inboxes provide async messaging with auto-resume. Teammates are Codex CLI processes that run autonomously in the background.

```
create_team → create_task (×N) → spawn_teammate (×N) → coordinate → shutdown → delete_team
```

## Quick Start

### Prerequisites

- **Node.js** >= 20
- **OpenAI Codex CLI** installed and configured (`codex` command in PATH)
- **Git** (for worktree support)

### Install

```bash
npm install -g mcp-codex-teams
```

### Configure in Claude Code

```bash
claude mcp add codex-teams -- npx -y mcp-codex-teams
```

### Configure in other MCP clients

Add to your MCP config (e.g., `claude_desktop_config.json`, Cursor, VS Code):

```json
{
  "mcpServers": {
    "codex-teams": {
      "command": "npx",
      "args": ["-y", "mcp-codex-teams"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "codex-teams": {
      "command": "mcp-codex-teams"
    }
  }
}
```

## Tools

12 tools organized around the team lifecycle:

### Team Management

| Tool | Description |
|------|-------------|
| `create_team` | Create a team with shared Git worktree. Always the first call. |
| `delete_team` | Delete the active team after all members are removed. Always the last call. |

### Teammate Lifecycle

| Tool | Description |
|------|-------------|
| `spawn_teammate` | Spawn a Codex CLI agent with enriched prompt (roster, tasks, inbox injected). Returns immediately. |
| `check_teammate` | Check process state, output tail, JSONL analytics, inbox status. |
| `force_kill_teammate` | Force-kill a teammate process. Does not remove from team. |
| `process_shutdown` | Full removal: kill process, reset owned tasks, remove from roster, delete inbox. |

### Task Graph

| Tool | Description |
|------|-------------|
| `create_task` | Create a task (starts as pending, no owner). |
| `update_task` | Change status, assign owner, manage dependencies with cycle detection. |
| `list_tasks` | Markdown table of all tasks with status, owner, blockers. |
| `get_task` | Full detail for one task including description and dependency graph. |

### Communication

| Tool | Description |
|------|-------------|
| `send_message` | DM, broadcast, shutdown request, or shutdown response. Auto-resumes inactive teammates. |
| `read_inbox` | Read messages with optional filters (unread, sender). |

## Typical Workflow

```
create_team("auth-feature")
  → create_task("Implement JWT middleware", "...")
  → create_task("Write auth tests", "...")
  → update_task(task2, addBlockedBy: [task1])
  → spawn_teammate("backend-dev", prompt: "...", role: "coder")
  → update_task(task1, owner: "backend-dev", status: "in_progress")
  → check_teammate("backend-dev")          # monitor progress
  → send_message(type: "message", ...)      # coordinate
  → process_shutdown("backend-dev")         # cleanup when done
  → delete_team()
```

Every tool response includes a **Next:** footer suggesting the logical next tools to call, making the workflow self-guiding for AI agents.

## Teammate Roles & Specializations

When spawning teammates, assign a role and optional specialization for domain-specific system prompts:

| Role | Specializations |
|------|----------------|
| **coder** | csharp, go, java, kotlin, nextjs, python, react, ruby, rust, supabase, supastarter, swift, tauri, triggerdev, typescript, vue |
| **planner** | architecture, bugfix, feature, migration, refactor |
| **tester** | graphql, playwright, rest, suite |
| **researcher** | library, performance, security |

Example:
```json
{
  "name": "api-dev",
  "prompt": "Implement the REST API endpoints for user management",
  "role": "coder",
  "specialization": "typescript",
  "context_files": ["src/routes/users.ts", "src/models/user.ts"]
}
```

## How It Works

### File-Backed State

All team data persists to `~/.codex-teams-mcp/`:

```
~/.codex-teams-mcp/
  teams/<name>/config.json            Team roster, worktree info, branch
  teams/<name>/inboxes/<agent>.json   Per-agent message inbox
  tasks/<name>/<id>.json              Task with deps, status, metadata
  tasks/<name>/.lock                  File lock for concurrent access
  templates/                          Role templates (auto-copied, customizable)
  sessions/                           JSONL session persistence
```

- Teammates can read each other's state directly from disk
- State survives server restarts (auto-detected on next call)
- All writes are atomic (tmp + rename) to prevent partial reads

### Shared Git Worktrees

`create_team` creates a Git worktree branch so all teammates operate on the same isolated copy of the codebase. No merge conflicts between teammates; clean merge back when done.

### Prompt Enrichment

Every spawned teammate receives an enriched prompt containing:
- Their identity (name, role, team membership)
- Full team roster (who else is on the team)
- Current task assignments (assigned + available)
- Unread inbox messages
- Common context (shared instructions)
- The user's actual task prompt

### Auto-Resume

When a teammate becomes inactive (process exits), their `conversationId` is stored. Sending them a message via `send_message` automatically resumes their Codex session with fresh context.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MAX_CONCURRENT_AGENTS` | `20` | Max parallel running teammates |
| `CODEX_MCP_CALLBACK_URI` | — | Static MCP callback URI passed to Codex CLI |
| `MCP_ENABLED_TOOLS` | all | Comma-separated tool whitelist for template filtering |
| `CODEX_ROTATE` | disabled | Set to `1` for API account rotation |
| `CODEX_MAX_TASKS` | `100` | Max concurrent tasks before eviction |
| `CODEX_MAX_OUTPUT_LINES` | `2000` | Ring buffer capacity per task output |

## MCP Resources

Read-only resources for monitoring:

| URI | Description |
|-----|-------------|
| `system:///status` | Server version, uptime, task/group counts |
| `task:///all` | All tasks with analytics summaries |
| `task:///{id}` | Detailed task state with JSONL event tail |
| `group:///all` | All groups with state summaries |
| `group:///{id}` | Detailed group state with DAG visualization |

## Development

```bash
git clone https://github.com/yigitkonur/mcp-codex-teams.git
cd mcp-codex-teams
pnpm install
pnpm build
pnpm test          # 298 tests, 17 suites
```

### Scripts

| Command | Description |
|---------|-------------|
| `pnpm build` | TypeScript compile + copy .mdx templates to dist/ |
| `pnpm dev` | Run via tsx (no build needed) |
| `pnpm test` | Jest in ESM mode |
| `pnpm test:coverage` | Coverage report (text + lcov + html) |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier |

### Project Structure

```
src/
  index.ts                Entry point — init + server start + shutdown
  server.ts               MCP stdio server, tool routing, resources
  types.ts                Constants, Zod schemas, shared types
  errors.ts               Custom error classes
  team/
    types.ts              Team/member/inbox/task types + Zod schemas
    config.ts             Team config CRUD (atomic writes)
    messaging.ts          File-backed inbox with locking
    tasks.ts              Task graph with dependency management
    spawner.ts            Codex CLI spawn/resume/kill
    prompt-builder.ts     Enriched prompt construction
    filelock.ts           O_EXCL file lock primitive
  tools/
    team-definitions.ts   12 MCP tool definitions with JSON Schema
    team-handlers.ts      Handlers with workflow-aware responses
  process/
    runner.ts             Codex process lifecycle + JSONL parse
  task/
    store.ts              In-memory task tracking with eviction
    state-machine.ts      Status transitions
  event/
    bus.ts                Pub/sub with scoped subscriptions
  templates/
    *.mdx                 4 base role templates
    overlays/*.mdx        28 specialization overlays
```

### Tech Stack

- **TypeScript 5.9** — ES Modules, strict mode
- **@modelcontextprotocol/sdk** — MCP protocol (stdio transport)
- **zod v4** — Runtime validation of all tool arguments
- **chalk** — Stderr diagnostics
- **Jest + ts-jest** — 298 tests across 17 suites

## License

ISC