Coordinate Agents

简体中文 · Documentation · Security

Coordinate Agents is a local collaboration workbench backed by a local-first coordination protocol and runtime for Codex and external AI coding agents. It offers lightweight interactive collaboration and structured task workflows while keeping the repository and local state under your control.

Choose Web Workspace for a low-overhead Codex + Antigravity terminal pair, or the Codex Plugin / CLI / MCP for durable Tasks, structured review, and explicit recovery. The Plugin is the recommended distribution for the structured workflow; Web runs through the standalone npm Runtime or a source checkout.

Two collaboration modes

Web task-group status describes terminal lifecycle, not implementation or review completion. Role prompts guide agent behavior; they are not an enforced workflow state machine. Both modes retain explicit user authorization for commit, push, and release as applicable to their workflow. The Web prompt forbids these actions without authorization.

The recording comes from npm run demo in an isolated Git repository. Its sanitized source transcript is available at assets/demo-transcript.txt.

Why Coordinate Agents

A capable coding agent can work alone. Coordination becomes useful when you want a second agent to implement while Codex keeps the specification and review boundary clear.

• Codex clarifies the task, records acceptance criteria, dispatches work, and reviews evidence.
• A configured Implementer CLI edits code and runs tests inside an owned execution session.
• The Agent Bus preserves task, message, review, session, and recovery facts locally.
• Release actions stay separate from implementation and require explicit user authorization.

How the structured workflow works

You
 |
 v
Codex: clarify -> specify -> dispatch --------------------+
 |                                                        |
 v                                                        |
Local Agent Bus -> configured adapter -> Implementer CLI  |
 ^                                      |                 |
 |                                      v                 |
 +----------- durable result + evidence -----------------+
 |
 v
Codex: review -> approve changes or request rework

The runtime owns only sessions it creates. Healthy sessions can be reused for review rework; failed or exited sessions require an explicit new dispatch. Detailed task, message, and session contracts live in the protocol documentation.

Quick Start

Install the Plugin from the canonical GitHub marketplace:

codex plugin marketplace add hogancv/coordinate-agents
codex plugin add coordinate-agents@coordinate-agents

Then open a Git repository in Codex App and start with one of these prompts:

Use $coordinate-agents to inspect this repository and explain the available coordination setup.

Use $coordinate-agents to configure my installed Antigravity or other coding-agent CLI as the Implementer.

Use $coordinate-agents to implement this task. Clarify acceptance criteria first, dispatch implementation, then review the result: <task>

The Plugin path does not require a global npm installation. For prerequisites, verification, upgrades, and uninstall steps, see Getting Started, Install with AI, and the Plugin end-to-end guide.

Example

Suppose you ask:

Use $coordinate-agents to fix the intermittent cache invalidation test. Preserve the public API, add a regression test, and do not release anything.

Codex turns that into a durable task, selects the configured Implementer adapter, opens or reuses an owned execution session, waits for implementation evidence, and reviews the diff and tests. A failed review returns concrete findings through the same task; a passing review still does not authorize a release.

Key Capabilities

• Durable local tasks, messages, review decisions, and runtime events.
• Additive Task Graph v1 validation with optional Intent Map v1 write-scope declarations, deterministic conflict-aware Graph Preflight with bounded risks and resource estimates, explicit bounded multi-wave advance, post-execution scope auditing, isolated aggregate integration/review, and facts-first recovery across worktrees and Sessions.
• Explicit Planner, Implementer, and Reviewer role boundaries.
• Adapter-based execution for exact configured CLI commands.
• Persistent, bounded, and inspectable execution sessions.
• Review rework that reuses healthy context without infinite retry loops.
• Recovery, explicit resume, bounded stop, and ownership-safe cleanup for interrupted graph execution; no filename/prose success inference or automatic retry loop.
• Explicit graph integration verifies completed subtask refs and applies them in sorted order in a separate review worktree; review refuses stale source facts or uncommitted aggregate changes, while conflicts remain inspectable and never modify the user checkout.
• A local Inspector timeline for tasks, sessions, and events.
• Separate review and release gates with exact authorization semantics.

Task Graph users can explicitly run task graph-integrate after all required subtasks succeed, then use task graph-review or the matching MCP tools to inspect and record the aggregate decision. The integration worktree, source refs, applied commits, conflict facts, and review evidence are durable; a REVIEW_APPROVED result never authorizes merge, push, tag, publish, deploy, or release.

At graph creation, users may add --intent-map <intent-map.json> or the MCP intentMap object. The companion map covers every subtask exactly once, defaults to scopePolicy: "warn", and records normalized repository-relative write patterns. Status, inspect, and plan distinguish legacy unavailable coverage from an explicitly empty writeIntent declaration. When coverage is available, planning greedily selects the stable subtask-ID order up to maxConcurrency, skips conservatively overlapping write intents, and returns bounded WRITE_INTENT_CONFLICT facts. After verified completion, the Runtime compares committed and uncommitted changes with the declaration before unlocking dependents. observe records drift, warn also exposes an INTENT_SCOPE_DRIFT warning while keeping success, and strict preserves the commit/worktree but records a recoverable failure. These checks never create dependency edges or mutate the user checkout.

Supported Agents and Adapters

The bundled reference workflow uses Codex as Planner and Reviewer. Implementers are selected through adapters:

Project command configuration takes precedence over user configuration, which takes precedence over the adapter default. The final executable identity is never guessed. See Codex CLI, Antigravity CLI, and the runtime comparison.

Adapter Contract v1

The package and Plugin payload expose the versioned validation boundary at adapter-sdk.mjs; npm consumers import @hogancv/coordinate-agents/adapter-sdk.mjs. Contract v1 covers adapter identity, capabilities, detection, configuration compatibility, argument-array launch plans, persistent-session initial input, and launch policy. The Runtime continues to own executable/path validation, process and Session lifecycle, bounded output, durable state, review, and release gates.

The public Adapter Conformance Kit runs the same Contract v1 checks against deterministic fake executables in isolated temporary roots, including paths with spaces and shell metacharacters. It returns bounded CI diagnostics and never contacts a provider or mutates user configuration. Explicit local modules can be registered with coordinate-agents adapter register <local-file>; only the selected regular .mjs, .js, or .cjs path is loaded, and descriptor/configuration failures leave user and project state unchanged. The module is trusted code running with current Node.js permissions; contract validation is not a malicious-JavaScript sandbox. See the bundled Adapter Contract v1 reference.

The built-in Codex CLI, Antigravity CLI, and generic CLI adapters are created through validated Contract v1 descriptors and pass this same conformance runner. Runtime session decisions use the frozen descriptor capabilities, while the legacy adapter metadata methods remain compatible.

For third-party authors, the External Adapter Author Guide walks through the public imports, Contract v1 methods, offline fixture, explicit trusted-local registration, and package payload. The complete minimal external Adapter example remains outside the built-in registry and requires no provider access.

The repository [Adapter SDK acceptance gate](./docs/adapter-conformance.md#repository-acceptance-ga