Skip to content
Back to search

coordinate-agents

Coordinate multiple AI coding agents through a local-first, recoverable Agent Bus.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hogancv--coordinate-agents/badge.svg)](/listings/hogancv--coordinate-agents)

HTML

<a href="/listings/hogancv--coordinate-agents"><img src="/api/listings/hogancv--coordinate-agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](./docs/getting-started.md), [Install with AI](./docs/install-with-ai.md), and the [Plugin end-to-end guide](./docs/plugin-e2e.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 205 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="./docs/assets/social-preview.jpg" alt="Coordinate Agents — local workspace for coding agents" width="960">
  3. </p>
  4. <p align="center">
  5. <a href="https://www.npmjs.com/package/@hogancv/coordinate-agents"><img src="https://img.shields.io/npm/v/%40hogancv%2Fcoordinate-agents?style=flat&amp;color=216384" alt="npm version"></a>
  6. <a href="https://www.npmjs.com/package/@hogancv/coordinate-agents"><img src="https://img.shields.io/npm/dm/%40hogancv%2Fcoordinate-agents?style=flat&amp;color=317c9d" alt="npm monthly downloads"></a>
  7. <a href="https://github.com/hogancv/coordinate-agents/actions/workflows/web-ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/hogancv/coordinate-agents/web-ci.yml?branch=main&amp;style=flat&amp;label=Web%20CI" alt="Web CI status"></a>
  8. <a href="./package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-43853d?style=flat" alt="Node.js 18 or newer"></a>
  9. <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-216384?style=flat" alt="MIT license"></a>
  10. </p>
  11. <p align="center"><strong>Two coding agents. One local workspace.</strong></p>
  12. <p align="center">
  13. <a href="#quick-start">Quick start</a> ·
  14. <a href="#what-you-can-do">Features</a> ·
  15. <a href="#how-default-collaboration-works">How it works</a> ·
  16. <a href="./docs/index.md">Documentation</a> ·
  17. <a href="./docs/changelog.md">Changelog</a>
  18. </p>
  19. <p align="center"><strong>English</strong> · <a href="./README.zh-CN.md">简体中文</a></p>
  20. ## Overview
  21. A local Web Workspace for working with coding agents in two persistent terminals.
  22. Use the default **Codex + Antigravity** pair to delegate implementation and review
  23. results, or choose **Custom Terminals** to bring your own CLI pair.
  24. Your projects, task history, terminal sessions, and collaboration receipts stay
  25. on your machine. Each agent uses its own CLI configuration and provider login.
  26. <img src="./docs/assets/coordinate-agents-promo.gif" alt="Coordinate Agents animated product demo" width="100%">
  27. ![Web Workspace preview](./docs/assets/web-workspace.png)
  28. > **Coming from v2.4?** v3 focuses the npm product on Web Workspace. Find the
  29. > [original v2.4.0 docs and migration guide](./docs/v2.4.md) for the old workflow and version-specific commands.
  30. ## Quick Start
  31. Install **Node.js >=18** and **Git**, plus the agent CLIs you want to use.
  32. For Default Collaboration, make sure `codex` and `agy` work and are signed in
  33. before creating a task. Coordinate Agents does not install the agent CLIs.
  34. Workspace settings allow choosing Antigravity tool permission mode. The adapter
  35. defaults to automatic approval via `--dangerously-skip-permissions`; choose prompt
  36. mode to require tool approval. Explicit saved arguments override the default.
  37. ```sh
  38. npx @hogancv/coordinate-agents@latest web --root "/path/to/project" --port 3000
  39. ```
  40. Open the printed localhost URL, check **Workspace settings**, and create a task.
  41. Choose **Default Collaboration**, then enter your request directly in Codex.
  42. Codex sends the implementation requirements to the paired Antigravity, waits
  43. for its receipt, reviews the changes, and reports back to you.
  44. Use `--port 0` to choose a free port. The startup folder is registered automatically;
  45. if it is not already a Git repository, startup initializes Git and local Workspace
  46. storage without creating a commit. A Codex Plugin is not needed.
  47. ### Published npm package and current source
  48. **The 3.0.2 Web release includes the features added after 3.0.1:** Git Changes
  49. and review feedback, Custom Terminals, desktop notifications, Collaboration
  50. Timeline/Health, and native Codex conversation recovery. Use `@3.0.2` for a pinned
  51. install, or verify npm `dist-tags.latest` before using `@latest`. The source
  52. checkout remains available for development; merging to `main` does not publish npm.
  53. ```sh
  54. git clone https://github.com/hogancv/coordinate-agents.git
  55. cd coordinate-agents
  56. npm ci
  57. node bin/coordinate-agents.mjs web --root "/path/to/project" --port 3000
  58. ```
  59. If you already have a checkout, run `npm ci` and the last command from its root.
  60. See [Getting started](./docs/getting-started.md) for the first-task walkthrough
  61. and [Troubleshooting](./docs/troubleshooting.md) for startup problems.
  62. ## What you can do
  63. | Capability | How it works in the current source |
  64. | --- | --- |
  65. | Default Collaboration | Codex clarifies, delegates, and reviews; Antigravity implements. Each task starts a fresh terminal pair. |
  66. | Custom Terminals | Choose two installed CLI executables, including the same CLI twice, with optional shared and per-terminal prompts. |
  67. | Multiple projects | Browse local folders, switch projects without closing background sessions, and search project/task history. |
  68. | Persistent terminals | Type directly, resize, focus one terminal, use Zen mode, and reconnect after page refresh. Close or restart sessions explicitly. |
  69. | Reopen the original Codex conversation | Supported local Codex CLI 0.163.x automatically saves the native conversation binding. Reopen task uses the saved UUID; Recover executor preserves a live Codex and rebuilds the missing executor. Completed terminal startup makes the task ready without an extra UUID confirmation. [Action table and fallback](./docs/codex-conversation-resume.md#action-table). |
  70. | Git Changes and review feedback | Inspect working-tree changes, select diff lines, and send review notes to the task's Codex after confirming its input is ready. |
  71. | Collaboration Timeline | Browse persisted dispatch and agent-report events by round. |
  72. | Collaboration Health | See missing progress receipts and session problems, with a configurable attention threshold. |
  73. | Desktop notifications | Opt into DONE, APPROVED, and FAILED receipt notifications on Windows 10/11 or macOS. |
  74. | Local history | Archive tasks or projects; clear archived conversations explicitly from settings. |
  75. | Bilingual interface | Switch between Simplified Chinese and English. |
  76. The [Workspace guide](./docs/inspector.md) explains settings, prompts, feedback,
  77. notifications, storage, and session lifecycle.
  78. ## How default collaboration works
  79. ```text
  80. You enter a request in Codex
  81. → Codex sends requirements to this task's Antigravity
  82. → Antigravity reports WORKING, implements, then reports DONE or FAILED
  83. → Codex reviews the diff and validation
  84. → Codex reports APPROVED, or requests changes in a new round
  85. ```
  86. The supplied `workspace-message.mjs` helper binds messages to the selected task
  87. and terminal pair. It records explicit cooperation reports; ordinary terminal
  88. output and `idle` do not prove that work is complete. `SENT` confirms input
  89. dispatch only. `DONE` means the agent reports implementation ready for review.
  90. `APPROVED` is Codex's reported review decision, not independent verification.
  91. **Workspace task status describes terminal lifecycle, not implementation or
  92. review completion.** Collaboration prompts guide agent behavior; they are not
  93. an enforced workflow state machine. Timeline and health views observe recorded
  94. facts and do not automatically dispatch, retry, restart, or review work.
  95. Each Web task uses the selected project's working directory. A new terminal pair
  96. does not create an isolated Git worktree, so avoid conflicting edits across tasks.
  97. ## Custom Terminals
  98. Choose **Custom Terminals** when you want to control the two agents and their
  99. instructions yourself. Commands must be executable names or absolute paths,
  100. without inline arguments or shell syntax. Configure project defaults in settings;
  101. each task snapshots its commands and optional prompts, including for restarts.
  102. Shared prompts are limited to 8 KB UTF-8 and per-terminal prompts to 4 KB.
  103. Preview or copy them, or explicitly send after checking that the target CLI
  104. is ready for multiline bracketed paste. Custom mode supplies no built-in
  105. Planner/Implementer roles, collaboration rounds, or Send to Codex feedback.
  106. Git diff viewing and copying remain available.
  107. ## Local data and permissions
  108. The server listens on loopback. Task records and session data live under the
  109. project's ignored `.agent-bus/`; the project registry lives in the user
  110. configuration directory. Data is local plaintext. Agent providers may still
  111. receive prompts and code according to each CLI's own configuration.
  112. Refreshing the page reconnects to existing sessions. Closing the browser or
  113. stopping the Web server is not a terminal-close action; use the explicit close
  114. controls when you want agents to stop. Archiving closes the associated terminals
  115. and hides records while preserving project source files. Clearing archived
  116. conversations permanently removes their stored task history.
  117. Agents run with their configured local permissions. Role prompts prohibit commit,
  118. push, and release without user authorization, but do not provide a sandbox or a
  119. technical release gate. Read [Security](./docs/security.md) and the
  120. [vulnerability reporting policy](./.github/SECURITY.md) before sharing diagnostics.
  121. ## Structured workflow and npm 2 migration
  122. The repository also retains a **local-first coordination protocol and runtime**
  123. for structured Tasks, Agent Bus handoffs, recorded evidence, Task Graphs, and
  124. explicit recovery. These are optional **GitHub Plugin / Legacy CLI / MCP**
  125. capabilities, separate from Web tasks and their collaboration receipts.
  126. The npm 3.x CLI exposes `web`, help, and version only. It does not install Skills
  127. or ship the structured Task/Graph API, MCP server, read-only Inspector, or public
  128. Adapter SDK. Structured Plugin versioning is independent of npm Web releases.
  129. To use the Plugin:
  130. ```sh
  131. codex plugin marketplace add hogancv/coordinate-agents
  132. codex plugin add coordinate-agents@coordinate-agents
  133. ```
  134. For the retained CLI, use `node bin/coordinate-agents-legacy.mjs` from source or
  135. pin `npx @hogancv/coordinate-agents@2.4.0`. Structured review approval
  136. (`REVIEW_APPROVED`) is separate from its `RELEASE_APPROVED` release authorization.
  137. See [Structured workflow](./docs/structured-workflow.md) and
  138. [Legacy Skill installation](./docs/legacy-ai-install.md).
  139. ## Development
  140. ```sh
  141. npm ci
  142. node bin/coordinate-agents.mjs web --port 3000
  143. npm test
  144. ```
  145. `npm test` runs the core suite. Use `npm run test:web` for Workspace tests,
  146. `npm run test:shared` for shared runtime contracts, `npm run test:plugin` for
  147. Plugin/MCP compatibility, and `npm run test:full` for the full regression suite.
  148. Release history is in [Changelog](./docs/changelog.md); distribution details are in
  149. [Web-first distribution](./docs/releases/v3-web-first.md).
  150. ## Documentation
  151. - Start: [Getting started](./docs/getting-started.md), [Workspace guide](./docs/inspector.md), [FAQ](./docs/faq.md), [Comparison](./docs/comparison.md).
  152. - Install and operate: [Install with AI](./docs/install-with-ai.md), [Troubleshooting](./docs/troubleshooting.md), [Security](./docs/security.md).
  153. - Structured workflow: [Plugin and Legacy CLI](./docs/structured-workflow.md), [Plugin E2E](./docs/plugin-e2e.md), [Protocol](./docs/protocol.md), [MCP](./docs/mcp.md), [Task Graph](./docs/task-graph-v1.md).
  154. - Runtime and adapters: [Sessions](./docs/session-runtime.md), [Event Journal](./docs/event-journal.md), [Adapter author guide](./docs/adapter-author-guide.md), [Conformance](./docs/adapter-conformance.md).
  155. - Indexes: [Documentation home](./docs/index.md), [中文入口](./docs/zh-CN/index.md), [Machine-readable index](./docs/llms.txt).
  156. - [Knowledge graph](./docs/knowledge-graph.md): explore the interactive bilingual graph within the documentation site. The [standalone HTML](./docs/public/graphs/coordinate-agents.html) can also be downloaded and opened locally. This is an imported snapshot; rendering requires the vis-network CDN.
  157. ## License
  158. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.