mcp-codex-teams

An MCP server that lets AI agents orchestrate multi-agent teams on top of OpenAI Codex CLI. 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

npm install -g mcp-codex-teams

Configure in Claude Code

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):

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

Or if installed globally:

{
  "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:

{
  "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

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