Coordinate Agents

简体中文 · Documentation · Security

Coordinate Agents is a local-first coordination protocol and runtime for Codex and external AI coding agents. It gives planning, implementation, review, recovery, and release approval explicit boundaries while keeping the repository—and its durable .agent-bus state—under your control.

The recommended distribution is the Codex Plugin from this GitHub repository. The npm package remains available for standalone runtime and compatibility workflows.

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 It 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.
• 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 from interrupted coordination using canonical local facts.
• A local Inspector timeline for tasks, sessions, and events.
• Separate review and release gates with exact authorization semantics.

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 runs built-in and external descriptors through the same kit and covers the Windows/macOS/Linux × Node.js 18/22 matrix without changing Task, Bus, Event Journal, Inspector, MCP, review, or release ownership.

Setup discovery and the existing MCP setup/Task tools expose the same additive adapters registry snapshot, including registered external identities and Contract capabilities. Discovery does not launch an adapter; configured external Agents contribute only their Contract-defined detection facts. Setup can select an external adapter without merging Agent, Adapter, and executable identities, and the canonical Task/persistent-Session path preserves exact project command > user command > adapter default precedence.

Local Inspector

Start the read-only local Inspector from a repository with an initialized Agent Bus:

npx @hogancv/coordinate-agents@latest inspector --port 3000

It presents task, session, and Event Journal timelines without making the browser the source of truth. Learn more in Inspector and Event Journal.

Standalone npm Runtime

The compatibility package exposes the installer, doctor, quickstart, task, agent, session, MCP, and Inspector commands:

npx @hogancv/coordinate-agents@latest --help

Use this path for legacy standalone Skill installation, external automation, or protocol debugging. The full command workflows are maintained in Getting Started and MCP integration.

Documentation

• Start here: AI installation contract, Getting Started, Install with AI, FAQ
• Core runtime: Protocol, Execution Sessions, Event Journal, MCP
• Operations: Inspector, Troubleshooting, MCP troubleshooting, Security
• Agents and choices: Codex CLI, Antigravity CLI, Comparison
• Adapter authors: Author guide, minimal external Adapter example
• Machine-readable index: llms.txt

Safety and Release Boundary

.agent-bus is local plaintext state and should stay excluded from version control. Never put credentials, tokens, cookies, private keys, or unredacted sensitive output in task records, fixtures, logs, or commits. The runtime refuses unsafe paths and never attaches to arbitrary processes.

Implementation completion and REVIEW_APPROVED are not release authorization. Merge, push, tag, publish, deploy, GitHub Release, and release-workflow actions require a separately described plan and the exact user approval RELEASE_APPROVED. See SECURITY.md for the comp