English · Português (Brasil) · Español · 简体中文
Give Codex a complex job. Get a clear plan and a checked result.
Keep long jobs understandable, make progress easy to follow, and return to a checked result after an interruption.
Install in one prompt · See an everyday example
MIT licensed · Installs for your user account · Does not change Codex settings
- A clear plan you can follow from the request to the finish.
- Accountable parts, each with a clear purpose and owner.
- A checked, recoverable result that can survive interruptions.
| Use it when | You probably do not need it when |
|---|---|
| The work has multiple dependent steps, files, or specialties. | The task is one small, obvious step. |
| Several independent pieces can move ahead safely. | One quick answer or tiny edit is enough. |
| An interruption would make progress hard to reconstruct. | You could easily restart from the original prompt. |
Add saved search to my app without breaking checkout.
- Make the finish line clear: identify the saved-search behavior, the checkout safeguard, and how each will be checked.
- Keep progress understandable: separate discovery, the focused change, and the regression check so every part has a clear purpose.
- Check before finishing: review the changed files and verification evidence; after an interruption, continue from recorded progress instead of starting over.
The task is finished only when saved search meets its acceptance check and the existing checkout checks still pass.
Ask Codex to follow the repository-owned installer:
Install https://github.com/alanhoff/agent-coordinator by following INSTALL.md
The procedure clones the repository to a temporary directory, records its commit, copies the self-contained skill/ directory for the current user, removes the temporary checkout, and reports the installed path and source commit. It replaces an existing destination only when that destination identifies itself as Coordinator.
Running Coordinator requires Python 3.11 or newer and no third-party runtime packages. Installation does not edit Codex settings or register global custom-agent profiles.
| Current-user location | What goes there |
|---|---|
~/.agents/skills/coordinator |
The skill, role profiles, references, Python adapters, and bundled runtime code |
~/.agent-coordinator |
Private sessions, locks, recovery data, and workflow state |
In a project, send this starter prompt:
$coordinator Review this project's README for confusing setup steps. Do not edit files.
Return the three highest-impact fixes, cite the evidence for each, and confirm that no files changed.
A successful response meets three conditions:
- Three fixes are ranked by impact.
- Each fix cites evidence from the project.
- The response confirms that no files changed.
Coordinator follows the same four steps for each job:
- Understand: make the requested outcome, constraints, and proof of success explicit.
- Divide: break the job into the smallest useful parts, with clear boundaries and dependencies.
- Do: work through ready parts in a safe order. Specialist agents are optional; when they are unavailable, Coordinator performs each part inline through the same process.
- Check and recover: inspect the result and its evidence, reconcile uncertain work before retrying, and finish only after requirements and blockers are resolved.
The durable command path compiles those steps into safe operations:
plan-apply → next → node-route-auto → node-claim → node-start → node-complete
↘ refine/split/reconcile as required ↗
workflow-complete
next is read-only and reports the next legal action class without embedding the full workflow state.
Does this require multiple agents?
No. When extra agent capacity is available, Coordinator can send independent pieces to separate workers; otherwise it completes them inline, one at a time.
Do I need to invoke it explicitly?
Yes. The documented prompt pattern starts each coordinated task with $coordinator; installation itself only places the skill and changes no settings.
What does it add to my project or settings?
It adds no persistent Coordinator-owned file to the target project and does not edit Codex settings or global custom-agent profiles. During initialization, it creates and removes one private-name file solely to detect the repository filesystem's case behavior; Windows determines this without a probe file.
What happens if work is interrupted?
A new Coordinator run can resume from private state. It marks work that may still be active for reconciliation before retrying, preserves completed evidence, and avoids starting an uncertain step twice.
Prompt patterns
Use an explicit $coordinator prefix and state the finish line. These patterns cover implementation, diagnosis, recovery, and evidence-only comparison.
$coordinator Ship the saved-search feature. Inspect repository instructions, preserve the acceptance
criteria, separate only independent work, validate the integrated behavior, and finish with material
evidence.
$coordinator Reproduce and diagnose the intermittent checkout test before changing production. Keep
diagnosis, the smallest owner-layer fix, and independent validation as dependent parts.
$coordinator Resume the interrupted schema migration workflow. Reconcile uncertain work before
retrying, preserve completed evidence, and validate rollback and forward migration behavior.
$coordinator Compare the proposed event-processing architectures against current repository
boundaries and requirements. State tradeoffs and missing evidence, then recommend one without
implementing either option.
Assessment and lifecycle
Coordinator records five 0–4 complexity dimensions: breadth, change surface, coupling, novelty, and verification. It separately records 0–4 ambiguity factors for the objective, inputs, boundaries, dependencies, and acceptance.
Default limits are inclusive: complexity total 6 or any dimension 3 requires splitting, while ambiguity total 4 or any factor 2 requires refinement. The default maximum refinement depth is 8.
assess → refine or split → route → claim → execute → validate → reassess
Every non-blocked assessable leaf must be current and executable before routing begins. Changed requirements or effective dependency results can make later work stale, so the fixed-point check repeats after relevant evidence changes.
Ownership, routing, and completion
- Each executable part has acceptance criteria, one role, and zero or more normalized repository-relative
write_scopes. - Empty scopes mean evidence-only work and require
change_surface=0. Artifact work requires a positive change-surface score and at least one scope. - Every new part declares descriptive evidence plus repeatable positive and negative proof commands. Success requires positive exit
0and negative nonzero; failure requires the inverse pair. - Independent live work cannot overlap scopes. Case comparison follows behavior detected from the target filesystem.
- Routing ranks only candidates advertised by the active runtime. If no current catalog is available or selection fails, execution inherits the parent model and effort.
- A claim records a SHA-256 baseline for every artifact scope. Completion requires each declared scope to remain materialized and to have changed during that attempt.
- Workflow completion reruns proofs for every non-exempt graph record, including decomposed and superseded history, and requires every pair to prove success. Requirements and blockers must also be resolved, with only allowed terminal states. Coordinator does not invoke or inspect a version-control system.
State inspection, including Windows
Persisted schema-v8 workflow documents live under ~/.agent-coordinator/workflows; v6 and v7 documents upgrade automatically, with their existing nodes permanently proof-exempt. These commands are read-only and never create, lock, repair, normalize, cache, or clean state.
python3 ~/.agents/skills/coordinator/scripts/coordinator_state.py list --json
python3 ~/.agents/skills/coordinator/scripts/coordinator_state.py status --workflow-id WORKFLOW --json
python3 ~/.agents/skills/coordinator/scripts/coordinator_state.py context --workflow-id WORKFLOW --json
python3 ~/.agents/skills/coordinator/scripts/coordinator_state.py next --workflow-id WORKFLOW --jsonIn Windows Command Prompt, use python and the current-user path:
python "%USERPROFILE%\.agents\skills\coordinator\scripts\coordinator_state.py" list --json
python "%USERPROFILE%\.agents\skills\coordinator\scripts\coordinator_state.py" status --workflow-id WORKFLOW --json
python "%USERPROFILE%\.agents\skills\coordinator\scripts\coordinator_state.py" context --workflow-id WORKFLOW --json
python "%USERPROFILE%\.agents\skills\coordinator\scripts\coordinator_state.py" next --workflow-id WORKFLOW --jsonWindows state lives under %USERPROFILE%\.agent-coordinator\workflows.
Docker demo
The demo builds a disposable Node.js container, installs Codex in it, and mounts this repository's Coordinator skill read-only. Set OPENAI_API_KEY in the ignored demo/.env file:
OPENAI_API_KEY=your-api-keyRun the demo from the repository root:
cd demo
./run.shEach run deletes demo/home/ before generating a fresh application, so preserve any output you need before running it again.
The generated application and its todos.db database remain in demo/home/app/. Coordinator state is stored in demo/home/state/, and Codex state is stored in demo/home/codex/. Compose resources are removed when the run finishes, while these bind-mounted files remain available for inspection.
The generated project provides its own npm start command. Run it with a current Node.js release:
cd demo/home/app
npm start