For people checking the technical details
Codex provides the messages. Coordinator decides when they matter.
Coordinator stays a thin layer around native Codex tasks: it gives several agents one goal, bounded ownership, and sparse inter-task communication without copying chats or becoming a second orchestration runtime.
Release status
v0.5.0 is the supported schema-2 release.
Install the exact public tag below. Projects stay disabled until the user explicitly enables or migrates each one after review.
codex plugin add codex-coordinator@codex-coordinator
Data contract
One task, one bounded JSON claim, one generated current view.
Claims are named by the exact native Codex thread UUID and capped at 4 KB. Allowed content is project and task identity, title, bounded goal, active/blocked status, revision, timestamps, concrete repository-relative paths, exclusive actions, dependencies, and the direct over-limit decision flag.
CURRENT.md is an active-only generated view, never a second authority. Unknown fields are rejected. Prompts, reasoning, transcripts, tool output, source code, provider responses, and full-turn ledgers are not allowed.
Mutation and communication path
Assign, talk when needed, work, release.
- When explicitly asked, one goal-scoped Coordinator reuses suitable related local tasks before creating any new local task.
- Every durable task gets one complete native goal plus a visible work boundary in the shared checkout.
- Native Codex inter-task messages carry only bounded communication that requires another task to act: assignments, terminal results, real dependencies, collisions, or releases. Routine progress remains pull-first in the compact claim.
- The Coordinator waits on exact completion or attention events and decides whether to accept, follow up, reuse, integrate, ask the user, or finish.
- Regenerate the active-only
CURRENT.mdview at lifecycle boundaries and move terminal ownership to a compact receipt that hot reads ignore.
The Coordinator never polls every task and never turns native messaging into an acknowledgement or status-check loop. An explicitly unattended goal may use one temporary native thread heartbeat, removed at the first terminal or user-decision boundary. Equal or ancestor paths warn case-insensitively. Tasks cooperatively commit reviewed exact files.
Fair comparison
Use the smallest ownership tool that fits.
| Approach | Best fit |
|---|---|
| One task | One coherent goal |
| Parent-owned subagent | Short parallel help inside one task |
| Worktree | Intentional file and Git-history isolation |
| On-demand Coordinator | Several durable Codex tasks that need clear ownership plus sparse native handoffs around one goal |
| Project manager | Cross-team, cross-machine schedules and reporting |
Core runtime
Zero third-party runtime dependencies
Requires Codex, Git, and Python 3.10+. Native Codex remains responsible for persisted goals, task execution, inter-task messages, status, and transcripts. SessionStart reads at most the marker, has a five-second timeout, and launches no process. Doctor is a manual read-only package compatibility check. Optional Mission Control is a manually started localhost page for one project; it refreshes only when asked and has no task controls. The core uses no database, daemon, queue, installer, pip package, or npm package.
Validation
Protection and overhead are both release gates.
Tests cover concurrent claims, disjoint work, bounded inter-agent communication, assignment provenance, the five-task default and user-approved increases, record privacy and size, revision safety, compact receipts, silent disabled startup, no process launcher, read-only Doctor, legacy preservation, and optional-tool isolation. Release additionally requires measured startup/list latency and an explicit user decision.