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, mechanically verified model profiles, 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. Version 0.8 verifies them instead of trusting the lead's declaration: the fixed lead and every teammate generation expose separate expected, requested, and observed profiles with VERIFIED, MISMATCH, UNVERIFIED, or PENDING status. For teammates, requested is populated only when the matching Agent PreToolUse call was actually accepted; hook-bypassed spawns remain UNOBSERVED instead of copying the expected profile into evidence. Because absence alone cannot prove why a hook did not run, observer diagnostics list both trust/reload and unsupported/bypassed-path possibilities rather than guessing one cause.

Team capacity is clearest with teammate_count, which excludes the fixed lead. The legacy max_members input still counts the lead. Stopped or failed members remain in history but free their active seat, so a completed specialist can be retired before a fresh independent reviewer joins.

3. Watch progress (optional)

The observer CLI shows resume reconciliation, agent lanes, exact decisions, tasks, leases/resources, acceptance, pending attention, coordination health, expected/requested/observed model profiles with preflight coverage, and a chronological public narrative 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.

Related MCP server: agent-pool-mcp

What it provides

• Fixed-lead phases with root-session identity, aliases, native Codex thread IDs, explicit teammate-seat capacity, rotating reviewers, and replacement provenance.

• Mechanically verified per-role model profiles for separate orchestrator, coder, explorer, and reviewer settings, using short-lived exact spawn tickets, Agent preflight hooks, metadata-only native attestation, and fail-closed work gates.

• 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.

• Exact decision rendezvous that pauses dependent work until the fixed lead answers the current request revision and the requester acknowledges that exact response; crossed or superseded instructions fail closed.

• 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.

• Claude-like coordination visibility through sanitized edit/test/search execution events, a concise narrative lead feed, automatic resume summaries, agent-lane observer snapshots, and contribution/DAG/decision-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 expected/requested/observed profiles
    |-- task DAG, attempts, acceptance, and release gate
    |-- two-stage liveness plus task/path/resource leases
    |-- typed mailboxes, exact decisions, plans, contracts, and checkpoints
    |-- sanitized execution events and narrative/agent-lane observation
    `-- 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 prepares and preflights exact spawn arguments, then independently attests the actual native model and reasoning metadata before allowing shared work. In the installed plugin, the trusted-local stdio runtime binds the fixed lead from per-call Codex request metadata, corroborates the root UUID, latest turn, model, effort, and freshness against native session records, and fences replays. CODEX_THREAD_ID remains a compatibility fallback. Callers normally omit session_id and parent_session_id; explicit IDs are retained for embedders and tests and must exactly match the authoritative root when present. Raw request metadata and native turn IDs are never persisted.

A typical run looks like this:

1. The lead creates an explicit phase, and the running fixed lead is attested against its real native root task metadata.

2. Each teammate is registered as profile_pending; the lead prepares a generation-specific spawn ticket, uses its exact arguments, and requires native post-spawn attestation before assigning work.

3. Teammates submit plans and contracts, challenge unclear interfaces, then atomically claim unblocked work with path/resource ownership.

4. Sync and heartbeats renew fenced task, path, and resource leases. One missed heartbeat preserves work as suspect; stronger evidence drives recovery.

5. Typed mailboxes carry durable peer coordination. A teammate that needs a lead ruling enters an exact decision rendezvous and resumes only after acknowledging the current response. Structured execution events make edits, tests, blockers, and checkpoints visible without raw transcript exposure.

6. 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

Model-profile enforcement is generation-specific. member_spawn_prepare returns a short-lived ticket containing the exact native task_name, model, reasoning_effort, fork_turns: "none", and root identity. Supported generic Agent calls are denied when those arguments are missing, changed, expired, reused, ambiguous, or invoked from the wrong root. The hook also verifies transcript_path metadata so a child hook that inherits the parent session ID cannot impersonate the fixed lead. While a verified caller root has any active spawn ticket, an unknown or omitted task_name is denied instead of being treated as an unrelated Agent call; authoritatively identified roots with no active ticket remain unaffected. Preflight verifies at most one candidate root: the authoritative runtime root, otherwise an exactly matching supplied session, otherwise one unambiguous task/ticket candidate. Ambiguity fails closed without sequential root scanning, and the path uses one expiry-aware read snapshot plus at most one persistence lock. After spawning, current Codex Agent output identifies the child as {"task_name":"/root/<task_name>"}. Codex Teams requires that exact derived path for the ticket, resolves it to the time- and root-scoped native child UUID with bounded retries, then reads only supported session_meta and turn_context records—not transcript or reasoning content. Transient metadata absence leaves the ticket retryable and the member fenced; manual member_spawn_attest can bound that window with retry_timeout_ms. Ambiguity and invalid metadata fail immediately instead of being retried as visibility races. Every resolver attempt has one wall-clock deadline covering directory discovery, metadata reads, and candidate processing; timeout aborts open read streams and returns UNVERIFIED.

Until the current generation is VERIFIED, it cannot claim tasks, acquire path or resource leases, publish implementation results, satisfy acceptance, or unblock release/finalization. A MISMATCH requeues work, releases ownership, and requires the host to stop or fence that child before replacing it. Unavailable or incompatible metadata becomes UNVERIFIED; the server never guesses. A later downgrade from VERIFIED atomically requeues owned work and releases task, path, resource, and waiter ownership. Historical audits use root/time-bounded identity reconstruction and append amendments rather than rewriting old claims.

Capacity-only team_create retries may increase teammate seats during roster/task-DAG bootstrap. Once task attempts, accepted contracts, leases, resource coordination, or implementation events exist, capacity is locked and the server returns concrete blockers plus reviewer-rotation guidance.

The same native worker UUID cannot be reused by another simultaneously active team phase. Fixed-lead resume checks also persist MISMATCH or UNVERIFIED amendments before returning an error, so observer and finalization blockers always reflect the latest native evidence. When the runtime supplies an authoritative current root, lead resume first requires it to equal the stored fixed-root UUID; a different root is rejected before the stored root is re-attested or team state is mutated.

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.

A decision-dependent task uses a stricter three-step gate than ordinary mail: decision_request, exact lead decision_respond, then exact requester decision_acknowledge. Request revision, request ID, response ID, member generation, task-lease generation, and a required retry-deduplication key are all fenced. Newer requests supersede older open revisions, stale acknowledgements fail, exact acknowledgement retries remain idempotent after the task moves on, and open decisions block release approval, automatic shutdown, and finalization. decision_list pages materialized threads with threadCursor/after_thread_id independently from its append-only history sequence cursor. Each thread carries only its current materialized revision, plus revisionCount and revisionsTruncated; use the independently paged history for the complete lifecycle. This keeps every response bounded even when one decision thread has many revisions.

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 a resume reconciliation summary, per-agent lanes, exact open-decision status, and a signal-focused narrative of direct excerpts, edits, tests, decisions, blockers, results, public message summaries, and flagged lifecycle events. --all-activity adds routine searches, reads, progress mirrors, and lifecycle noise. This is partial public visibility, not raw agent output. Reconciliation also computes overdue heartbeat, task, path, and named-resource leases at observation time, so the dashboard cannot report healthy merely because a recovery sweep has not persisted suspect state yet.

codex-teams report or the team_report/archive_report tools summarize expected/requested/observed profile status and native identity, member contributions, task/DAG shape, attempts and requeues, mailbox acknowledgement/handling/response latency, exact decision response and acknowledgement latency, structured execution counts, 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.

execution_publish accepts only allowlisted search, read, edit, test, blocker, and checkpoint fields. It rejects raw commands, logs, output, arbitrary metadata, absolute or drive-relative paths, credential-like labels, invalid kind/status combinations, and unbounded counters. Checkpoint events must reference a real checkpoint saved by the same member generation. These events share the activity retention and cursor rather than creating a second transcript. narrative_tail projects the safe public stream into concise, deterministic lead commentary.

The narrow execution-event labels reject common credential-like patterns, but free-form progress and activity are not general DLP surfaces. Keep credentials, private data, hidden reasoning, and large logs out of every public field.

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 and renders a local terminal dashboard; MCP cannot add custom native cards to Codex Desktop.

• Mailbox wakeRequested records wake intent but does not schedule an inactive model turn. The orchestration skill pairs urgent shared messages with native agent steering.

• Plugin hooks guard supported generic Agent tool calls, but hooks can be disabled, declined as untrusted, or bypassed by specialized host paths. Metadata-only post-spawn attestation is therefore mandatory. If Codex changes or removes the supported native metadata shape, work fails closed as UNVERIFIED.

• Codex Teams does not reproduce Claude's split-pane interface or expose hidden reasoning. It provides a Claude-like coordination narrative, exact decision synchronization, partial structured 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