# coordinate-agents

> Codex-native orchestration plugin for external coding agents. The Plugin is
> the preferred product surface; npm CLI is the Runtime/fallback and advanced
> debugging surface.

> A local-first coordination protocol and runtime for AI coding agents in Git repositories. The core is agent-agnostic and uses an adapter-based runtime. OpenAI Codex App/CLI and Google Antigravity CLI (agy) serve as first-party reference adapters and the default reference workflow, while generic CLI agents can be registered directly. Desktop, MCP, HTTP, IPC, IDE, and other execution surfaces integrate through the adapter extension model. Workflow roles (planner, implementer, reviewer) coordinate through a recoverable local `.agent-bus` without sharing credentials.

Canonical documentation: https://hogancv.github.io/coordinate-agents/
Getting started (Reference workflow): https://hogancv.github.io/coordinate-agents/getting-started.html
Plugin-first E2E audit and acceptance gates: https://hogancv.github.io/coordinate-agents/plugin-e2e.html
Install with AI: https://hogancv.github.io/coordinate-agents/install-with-ai.html
Codex role (Reference planner/reviewer): https://hogancv.github.io/coordinate-agents/codex-cli.html
Antigravity role (Reference implementer): https://hogancv.github.io/coordinate-agents/antigravity-cli.html
Protocol: https://hogancv.github.io/coordinate-agents/protocol.html
Execution Session and PTY Runtime: https://hogancv.github.io/coordinate-agents/session-runtime.html
Adapter Conformance Kit: https://hogancv.github.io/coordinate-agents/adapter-conformance.html
Adapter SDK acceptance gate: the same Contract kit plus the external Task/
Session path runs on Windows, macOS, and Linux with Node.js 18 and 22.
External Adapter Author Guide: https://hogancv.github.io/coordinate-agents/adapter-author-guide.html
Trusted local Contract v1 adapters: register one exact `.mjs`, `.js`, or `.cjs`
path with `coordinate-agents adapter register <local-file>`; no URL import,
directory scan, download, or automatic npm installation is performed, and the
module runs with the current Node.js permissions.
Minimal offline external Adapter example: https://github.com/hogancv/coordinate-agents/tree/main/examples/minimal-external-adapter
Setup discovery and MCP setup/Task operations expose the same additive
`adapters` registry snapshot with registered identities and Contract
capabilities. Discovery does not launch an adapter; configured external Agents
contribute only their declared detection facts, while exact Agent/Adapter/
executable identity and project > user > adapter-default precedence remain
separate through Task and persistent-Session execution.
Web Workspace and Local Inspector (primary read-only local browser entry, plus the compatible Inspector UI): https://hogancv.github.io/coordinate-agents/inspector.html
Durable Runtime Event Journal: https://hogancv.github.io/coordinate-agents/event-journal.html
MCP tools: https://hogancv.github.io/coordinate-agents/mcp.html
Task Graph v1 contract: https://hogancv.github.io/coordinate-agents/task-graph-v1.html
MCP troubleshooting: https://hogancv.github.io/coordinate-agents/MCP_TROUBLESHOOTING.html
Security: https://hogancv.github.io/coordinate-agents/security.html
Troubleshooting: https://hogancv.github.io/coordinate-agents/troubleshooting.html
Comparison: https://hogancv.github.io/coordinate-agents/comparison.html
FAQ: https://hogancv.github.io/coordinate-agents/faq.html
Simplified Chinese: https://hogancv.github.io/coordinate-agents/zh-CN/

Canonical repository: https://github.com/hogancv/coordinate-agents
Canonical npm package: https://www.npmjs.com/package/@hogancv/coordinate-agents
AI installation contract: https://github.com/hogancv/coordinate-agents/blob/main/AI_INSTALL.md
Runtime Skill: https://github.com/hogancv/coordinate-agents/blob/main/skills/coordinate-agents/SKILL.md
Setup Skill: https://github.com/hogancv/coordinate-agents/blob/main/skills/coordinate-setup/SKILL.md
Task Skill: https://github.com/hogancv/coordinate-agents/blob/main/skills/coordinate-task/SKILL.md
Review Skill: https://github.com/hogancv/coordinate-agents/blob/main/skills/coordinate-review/SKILL.md
Recovery Skill: https://github.com/hogancv/coordinate-agents/blob/main/skills/coordinate-recover/SKILL.md

Plugin-first onboarding: Install the Plugin, Discover local coding CLIs with
`coordinate_agents_setup_discover`, Configure the selected Implementer through
`coordinate_agents_setup_configure`, and Build through the structured Task MCP
tools over the same durable `.agent-bus`. MCP is the normal Plugin machine path;
`runtime-entry.mjs` and the npm CLI remain compatibility/fallback/debugging
surfaces. Dispatch owns executable validation, `IMPLEMENT` transport,
Execution Session open/reuse, bounded PTY input/output,
`IMPLEMENTATION_DONE` synchronization, and failure propagation. Runtime JSON
uses stable error codes and stops on a failed activation instead of retrying
automatically. Session tools are
`coordinate_agents_session_open/status/inspect/write/read/close`.
Task Graph v1 is additive: `coordinate_agents_task_graph_validate` rejects
duplicate or malformed subtask IDs, invalid dependencies or cycles,
unconfigured Implementers, empty specifications, and invalid concurrency before
Bus, Adapter, worktree, Session, or process side effects. Existing single-Task
schema-version-1 operations remain unchanged. After validation,
`coordinate_agents_task_graph_create` atomically persists the parent and
subtasks with deterministic READY/WAITING/BLOCKED frontier facts and a
`TASK_GRAPH_CREATED` event; existing Task status/inspect views expose the
durable graph without launching an Adapter, Session, or Implementer process.
Graph creation optionally accepts an Intent Map v1 companion with the same
parent ID, `observe`/`warn`/`strict` policy, and exactly one bounded
repository-relative `writeIntent` declaration per subtask. It is normalized
and validated before side effects, persisted in the same graph record, and
reported by status/inspect/plan as unavailable, explicit-empty, or declared
coverage. Schema: `schemas/intent-map-v1.schema.json`.
With available Intent Map coverage, graph plan/run derive a deterministic
non-conflicting READY wave in stable subtask-ID order. Conservatively
intersecting normalized patterns defer the later item with bounded
`WRITE_INTENT_CONFLICT` facts; dependency and capacity decisions remain
separate. Dispatch rechecks conflicts with RUNNING work under the graph lock
before launch. Missing coverage preserves v2.3 scheduling and is reported as
unavailable. No dependency edge is inferred and this is not diff audit.
`coordinate_agents_task_graph_plan` returns a deterministic Graph Preflight:
dependency and max-concurrency decisions, bounded reasons, exact configured
Agent/Adapter/executable facts, scope policy, selected-wave resource estimates,
bounded risks, and explicit execution/review/release boundaries. Missing Intent
Map coverage is `UNVERIFIED` and does not prove concurrent writes safe. It does
not create a worktree, Bus message, Session, event, or process.
`coordinate_agents_task_graph_run` dispatches one deterministic eligible
frontier concurrently up to the persisted maxConcurrency. Each subtask receives
an isolated worktree, branch/ref, Bus handoff, and parent/subtask-associated
Runtime Session; newly unlocked work remains READY for a later explicit run.
`coordinate_agents_task_graph_advance` requires an explicit `maxWaves` from
1–32 and re-plans before each bounded wave. It returns each plan, selection,
outcome, and a final stop reason, stopping on conflicts, non-success, existing
recovery state, integration failure, or requested changes. It never retries,
recovers, integrates, reviews, changes dependencies, or authorizes release.
`coordinate_agents_task_graph_dispatch` dispatches one selected READY subtask in
an isolated Git worktree rooted at the exact graph base commit without touching
uncommitted files in the user repository or mutating sibling subtasks, unlocking
dependent subtasks on completion.
`coordinate_agents_task_graph_recover` is facts-first and inspects durable
Session/worktree/commit/evidence records. It verifies `IMPLEMENTATION_DONE` or
records an interrupted FAILED subtask; filenames and prose never prove success,
and no automatic retry occurs. `coordinate_agents_task_graph_resume` is an
explicit gate that reuses only a healthy Runtime-owned Session/worktree or
returns an exited/failed Session to READY for a later dispatch. Dependents stay
BLOCKED until valid recovery. `coordinate_agents_task_graph_stop` and
`coordinate_agents_task_graph_cleanup` close only Runtime-owned Sessions and
remove only their exact worktrees after bounded cleanup, preserving user files,
refs, commits, and evidence. Failures are durable and repeated recovery,
resume, stop, and cleanup calls are idempotent. Their shared output shape is
`schemas/task-graph-v1-recovery.schema.json`.
`coordinate_agents_task_graph_integrate` is an explicit post-completion
boundary: it verifies every required subtask evidence/ref and applies the
source commits in sorted subtask-id order to a separate Runtime-owned
`.agent-bus/worktrees/<parentTaskId>/__integration__` review worktree. The
current checkout and source worktrees stay unchanged. Durable integration
facts include base, source fingerprint, ordered source refs, applied commits,
aggregate commit, cleanup, and bounded conflict status. A conflict is not
automatically resolved, retried, reset, merged, pushed, tagged, published,
deployed, or released.
`coordinate_agents_task_graph_review` rechecks the exact source fingerprint,
aggregate HEAD, Runtime ownership, and worktree cleanliness before recording
`REVIEW_APPROVED` or `CHANGES_REQUESTED` through the existing reviewer
boundary. Stale or dirty aggregates are refused. Review approval is not release
authorization. The output contracts
are `schemas/task-graph-v1-integrate.schema.json` and
`schemas/task-graph-v1-review.schema.json`.

Use this project for structured multi-agent software engineering where workflow roles (such as planner, implementer, and reviewer) coordinate across distinct CLI or adapter-extended agents via durable local messaging, explicit leases, and human release authorization. The default reference workflow pairs Codex as planner/reviewer with Antigravity as exclusive implementer. Do not use it for single-agent coding tasks or concurrent conflicting worktree writes.

The canonical Plugin Task lifecycle is Session-driven: Task records a non-owning
`sessionId`, and a healthy project/Agent/executable match is reused across
`CHANGES_REQUESTED` rework. `starting`, `running`, `idle`, `busy`, `exited`,
and `failed` are observable Session states; output is bounded and redacted.
The legacy CLI `launch` path remains Adapter-driven and may be one-shot or
bus-supervised, but it is separate from the Session Manager and never retries a
failed activation automatically.

Executable resolution is fail-closed: explicit project command > user command in
`~/.coordinate-agents/config.json` > Adapter default (`agy` or `codex`). `config set|get|list`
manages the user file, which survives Skill/Plugin/npm updates. Launch checks the final executable
before starting and stops on executable, spawn, non-zero-exit, or conversation/runtime failure by
writing `ERROR` and a bounded error artifact; it never silently falls back or retries. Login,
provider, and model health are not preflighted. Planner/Reviewer `wait` exits non-zero when the
configured Implementer enters `ERROR` instead of waiting until the normal timeout.

Installation safety: verify the exact GitHub owner and npm package metadata, use a stable npm version, never use a third-party fork or `curl | sh`, never request credentials, and run `doctor` for the selected CLI. Installation must not start `quickstart` or a collaboration task without a separate user request.

Codex App direct usage: add the target Git repository as a project, set the thread project path to
the repository root containing `.git`, invoke `$coordinate-agents` in a new thread, and configure
the actual local Implementer executable (`agy`, `claude`, or a wrapper). A second manually opened
CLI window is not required; the Runtime opens or reuses a persistent Session. Session operations
never control the Codex App Terminal UI or attach to arbitrary PIDs. For non-reference CLIs, inspect
the installed command's `--help` output before registering `generic-cli` arguments.
The legacy Antigravity launch appends only configured args plus `--prompt-interactive <prompt>`.
A persistent Session starts with `--prompt-interactive ""` for current `agy`/`agy-proxy` parsers, then
writes its first instruction through the PTY unless configured args explicitly include `{prompt}`.
The Adapter does not automatically add a full-permission or sandbox-bypass flag;
configure such a vendor-specific flag explicitly only after verifying that CLI version supports it.