Codex Teams

Codex Teams is an open-source multi-agent orchestration plugin for OpenAI Codex. Inspired by Claude Code Agent Teams, it coordinates native Codex subagents through an MCP server with shared tasks, direct mailboxes, heartbeats, leases, stale-agent recovery, and live observation.

If you are looking for Claude Agent Teams-style coordination in Codex, this project adds the missing shared team layer while leaving Codex responsible for spawning and running its own native agents.

Independent project. Not affiliated with or endorsed by OpenAI or Anthropic.

Quick start

1. Install from GitHub

Add this repository as a Codex plugin marketplace, then install the plugin:

codex plugin marketplace add GekkoQuest/codex-teams
codex plugin add codex-teams@gekkoquest

Restart Codex and open a new task so the bundled skill and MCP tools are loaded. You need Node.js 18 or newer and a current Codex release with plugin support.

To pick up a newer version later:

codex plugin marketplace upgrade gekkoquest
codex plugin add codex-teams@gekkoquest

2. Start a team

Use the bundled skill explicitly in your prompt:

Use $codex-teams:orchestrate-agent-teams to implement this feature.

Form a fixed lead with three teammates: architect, implementer, and reviewer.
Require plan approval before edits, create dependency-aware shared tasks, use
direct teammate messages and heartbeats, and finalize the team cleanly.

You can also choose different model and reasoning profiles for the lead and workers:

Lead: gpt-5.6-sol with xhigh reasoning
Teammates: gpt-5.6-sol with medium reasoning

Model names and effort levels must be supported by the Codex version running the team.

3. Watch progress (optional)

The observer CLI shows phases, members, tasks, resources, acceptance, pending attention, coordination health, and public activity excerpts without relying on lead commentary. Clone the source once, then run it from that checkout:

git clone https://github.com/GekkoQuest/codex-teams.git
cd codex-teams
node scripts/codex-teams.mjs resolve --identifier build-phase
node scripts/codex-teams.mjs watch --team build-phase
node scripts/codex-teams.mjs watch --team build-phase --activity 20
node scripts/codex-teams.mjs watch --team build-phase --all-activity
node scripts/codex-teams.mjs report --team build-phase
node scripts/codex-teams.mjs report --session ROOT_TASK_ID

The runtime has no third-party dependencies. To make the shorter codex-teams watch ... command available globally, run npm link once from the checkout. Installing the Codex plugin itself provides the skill and MCP server; it does not install the package binary globally.

What it provides

• Fixed-lead phases with root-session identity, aliases, native Codex thread IDs, rotating reviewers, and replacement provenance.
• Per-role model profiles for separate orchestrator, coder, explorer, and reviewer model or reasoning settings.
• Shared work DAGs with dynamic dependencies, readiness wakeups, atomic claims, attempt history, fenced transfers, review/barrier tasks, and a unique revision-bound release gate that becomes stale after material mutations.
• Two-stage recovery that treats one missed heartbeat as suspicion, uses native liveness evidence, parks idle agents, and requeues only after stronger evidence or task-lease expiry.
• Direct coordination through typed/prioritized/threaded mailboxes, retry deduplication, explicit seen/handled/responded states, plan approval, shared versioned contracts, and graceful shutdown handshakes.
• Ownership and capacity leases for atomic path batches plus named build, browser, device, port, or migration slots with queued wakeups.
• Acceptance and evidence through required criteria, explicit user-approved deferrals, release gating, and clean/recovered/failed closure quality.
• Resumability through acknowledgement page tokens, generation fencing, phase aliases, individually bounded checkpoints, and complete append-only task/result/plan/checkpoint history.
• Live and post-run visibility through signal-focused observer snapshots, a terminal dashboard, bounded public activity, and contribution/DAG/latency/ recovery reports for live teams or archives.
• Lifecycle history with reliable finalization, archives, confirm-gated pruning, and rejected-conflict audit evidence.
• Optional capability tokens for deployments that cross a trusted local user or workspace boundary.

How it works

Codex task (fixed lead)
|-- phase: build (team alias)
|   |-- native Codex subagent: architect
|   |-- native Codex subagent: implementer
|   `-- native Codex subagent: reviewer
`-- codex-teams MCP server
    |-- phases, roster provenance, and model profiles
    |-- task DAG, attempts, acceptance, and release gate
    |-- two-stage liveness plus task/path/resource leases
    |-- typed mailboxes, plans, contracts, and checkpoints
    |-- public progress/activity plus live/post-run reports
    `-- truthful closure, events, and archives

The MCP server is the coordination layer, not a model launcher. The lead uses Codex's native multi-agent tools to spawn, steer, wait for, and stop teammates. Codex Teams gives those agents a common task board and durable protocol.

A typical run looks like this:

1. The lead creates an explicit phase, acceptance matrix, roster, task DAG, and optional named resources.
2. Teammates submit plans and contracts, challenge unclear interfaces, then atomically claim unblocked work with path/resource ownership.
3. Sync and heartbeats renew fenced task, path, and resource leases. One missed heartbeat preserves work as suspect; stronger evidence drives recovery.
4. Typed mailboxes carry questions, requirements, gates, reviews, handoffs, and wake intent. Checkpoints make compaction or native replacement resumable.
5. The lead verifies evidence, completes the release gate, resolves high-priority attention, shuts teammates down, and finalizes a truthful durable record.

Coordination and recovery guarantees

Codex Teams separates uncertainty from abandonment. A missed heartbeat first marks a teammate suspect while its task and leases remain intact. Native running or waiting evidence restores it as a recorded false positive. An idle suspect is parked after repeated sweeps. Work is destructively requeued only when its task lease expires or the native host reports the thread stopped or failed.

A native teammate that has finished one turn but can still receive follow-up work is waiting, even when the host labels that turn done or completed. Treat stopped as terminal evidence only after an approved shutdown or a genuine unexpected stop. Recording a resumable turn as stopped creates lead attention and prevents the mistake from silently auto-finalizing the team.

Reactivation increments a member generation; every reclaimed task increments a lease generation. Old native turns are fenced from later writes. Controlled task transfers preserve both attempts and release linked ownership before the recipient claims. Batch path acquisition is atomic, and rejected overlaps are retained in the audit trail.

High/urgent and blocker/gate messages remain finalization blockers until they are handled, answered, or legitimately cancelled. Merely opening one does not count as coordination completion. Required acceptance criteria need evidence or an explicit user-approved deferral, and the lead-owned release gate cannot pass while other work or acceptance remains unresolved. Its approval is tied to the current release revision; later task, DAG, acceptance, terminal-result amendment, or accepted-contract replacement makes that approval stale and requires the gate to be completed again.

A teammate's shutdown approval means it is ready for the host to stop it; it is not proof that the native Codex thread terminated. Clean finalization requires the lead to pair each shutdown request with native follow-up messaging, receive the approval, stop that thread, and record the resulting native liveness evidence; member_update: stopped cannot substitute for that observation.

Closure records one of closed_cleanly, closed_with_recovery, or closed_with_failures; reports never silently label a recovered or forced run as clean.

Live observation and post-run review

The default observer shows signal-focused public activity: direct excerpts, decisions, blockers, results, public message summaries, and flagged lifecycle events. --all-activity adds routine progress mirrors and lifecycle noise. This is partial public visibility, not raw agent output.

codex-teams report or the team_report/archive_report tools summarize model profiles and member contributions, task/DAG shape, attempts and requeues, mailbox acknowledgement/handling/response latency, liveness recovery, path and named-resource use, acceptance evidence, closure quality, and warnings. Use report --session ROOT_TASK_ID to compare discovery, build, review, or release phases from one Codex task.

Public progress and activity

Codex Teams supports live progress visibility, but it does not expose raw model transcripts or hidden chain-of-thought reasoning.

progress_publish and activity_publish accept short excerpts deliberately marked as public. Activity summaries are limited to 2,000 characters and the newest 5,000 records are retained with monotonic cursors. Automatic lifecycle entries use fixed allowlisted text and never copy mailbox bodies, prompts, task results, errors, credentials, or private reasoning.

The server does not secret-scan text that an agent explicitly publishes. Keep credentials, private data, hidden reasoning, and large logs out of public progress and activity.

Security and limitations

• The default stdio setup uses trusted_local coordination identities. Use capability-token mode only when a custom transport crosses a local trust boundary.
• Capability tokens are returned once and stored as hashes, but they do not replace TLS, transport authentication, sandboxing, or native Codex permissions.
• Path leases coordinate writers; they do not enforce filesystem access.
• The observer CLI reads local state as an administrator.
• Mailbox wakeRequested records wake intent but does not schedule an inactive model turn. The orchestration skill pairs urgent shared messages with native agent steering.
• Codex Teams does not reproduce Claude's split-pane interface or expose hidden reasoning. It provides the coordination protocol, partial public activity, a terminal observer, and post-run reports.

State is stored under CODEX_TEAMS_DATA_DIR, PLUGIN_DATA/codex-teams, or ~/.codex/codex-teams, in that order. Do not commit that runtime state.

Development

Clone the repository and run the built-in checks:

git clone https://github.com/GekkoQuest/codex-teams.git
cd codex-teams
npm run check
npm test
npm run smoke

There is no dependency installation step: the server, CLI, and tests use only Node.js standard-library APIs.

For direct MCP development without installing the plugin, point Codex at the local server using an absolute checkout path:

[mcp_servers.codex_teams]
command = "node"
args = ["./mcp/server.mjs"]
cwd = "<absolute-path-to-codex-teams>"
startup_timeout_sec = 10
tool_timeout_sec = 60

Documentation

• Example prompts
• Example AGENTS.md
• Team protocol and recovery semantics
• Changelog

License

MIT