mcp-codex-agent-teams

Production MCP server for orchestrating Codex-powered agent teams with:

• Team lifecycle management
• Task graph orchestration (DAG, owner assignment, dependency safety)
• Lead/teammate inbox messaging
• Process-safe Codex execution and monitoring
• Git worktree/branch isolation per team
• Guided tool responses with "what to do next" steering

Why This Package

mcp-codex-agent-teams ports teammate-style orchestration into a Codex-native MCP server so agentic workflows are reliable, observable, and repeatable in real repositories.

Core Features

• Shared team worktree per team with dedicated branch isolation
• Teammate runtime scheduling with concurrency safeguards
• Task lifecycle (pending, in_progress, completed, deleted) and cycle prevention
• depends_on scheduling support and dependency-aware execution patterns
• Inbox protocol for direct messages, broadcast, plan/shutdown signals
• Runtime inspection (agent_check) with optional output tails
• Auto-commit support after team completion
• Response guidance footer on every tool call:
  • Success: Next Tool Suggestions
  • Error: Recovery Guidance

Requirements

• Node.js >= 20
• codex CLI installed and authenticated
• Git repository for real worktree execution flows

Install Codex CLI (if needed):

npm i -g @openai/codex
codex --help

Installation

npm i -g mcp-codex-agent-teams

Or run without global install:

npx -y mcp-codex-agent-teams

MCP Client Configuration

Example mcp_servers.json entry:

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

Persistent State

All state is stored under:

~/.mcp-codex-agent-teams

Includes:

• teams/ team configs and inboxes
• tasks/ team task files
• groups/ wave/group orchestration records
• sessions/ runtime session persistence

Tool Surface

Team

• team_create
• team_delete
• team_read_config

Agents

• agent_spawn
• agent_force_stop
• agent_check
• shutdown_process_approved

Messaging

• message_send
• inbox_read

Tasks

• task_create
• task_update
• task_list
• task_get

Recommended Workflow

1. team_create
2. task_create (create all major work units)
3. task_update (owner + dependency edges)
4. agent_spawn (start teammates)
5. agent_check / inbox_read / message_send (coordinate)
6. task_update (mark progress/completion)
7. shutdown_process_approved (if requested)
8. team_delete (cleanup when done)

Tool responses include explicit next-step guidance to keep orchestration tight and predictable.

Quick CLI Validation (mcp-cli)

mcp-cli info codex-teams
mcp-cli info codex-teams agent_spawn
mcp-cli call codex-teams team_create '{"team_name":"demo-team","base_cwd":"/path/to/repo"}'
mcp-cli call codex-teams task_create '{"team_name":"demo-team","subject":"Implement","description":"Build feature X"}'
mcp-cli call codex-teams task_list '{"team_name":"demo-team"}'

Development

pnpm install
pnpm build
pnpm test --runInBand
pnpm lint

Run locally:

pnpm dev

Release

• npm package: mcp-codex-agent-teams
• GitHub repo: yigitkonur/mcp-codex-agent-teams
• CI validates build, tests, lint, formatting
• Publish workflow uses NPM_TOKEN GitHub Actions secret

Security Notes

• This server can execute Codex tasks that run commands in repo worktrees.
• Use least-privilege repos/tokens in CI.
• Review teammate prompts and ownership transitions before execution.

License

ISC