CoAgent8 - Cooperating coding agents

Documentation

CoAgent8 lets the coding agent you work with ask another one. It is an MCP server that puts Codex, Claude Code and Antigravity (agy, which runs Gemini and other models) behind the same seven tools: your agent requests a second opinion or an independent review of your Git changes, or delegates a code change, and gets the other agent's answer back in the chat. Consultations and reviews run in a read-only profile; a delegated change edits the workspace. Every agent runs on your own installed and signed-in CLI.

Contents: Status | Quick start | Features | Tools | Skills | VS Code extension | Configuration | Known limitations | Reporting problems | Contributing

Status

0.7.0 is the current release; 0.6.0 was the first for testers, and 0.8.0 will be the first release candidate. Every version below 1.0.0 is a preview, with the same version number on GitHub, npm and VS Code. On npm each release appears first as coagent8@next; latest follows once the version has proved stable.

In 0.7.0: consultations and reviews by another agent in a read-only profile, model selection by price with your approval for expensive models, continuable sessions with history, diagnostics, skills and the VS Code extension. New in 0.8.0, on develop and not released yet: delegating a code change to another agent, which runs in the background and wakes Claude Code when it ends, with an optional loop in which CoAgent8 runs your checks and an independent review and returns failures to the agent; reviews of large changes in parts; and checks CoAgent8 runs before a review. This README describes develop, so features marked 0.8.0 are not in the published packages. Several delegated agents can run at once under one budget, in disjoint scopes of a work tree or in separate Git worktrees. Not yet available: an agent that itself delegates to others. That is the next step in the roadmap.

Related MCP server: codex-fusion-mcp

Quick start

You need Node.js 24 or later and at least one of these CLIs, installed and signed in:

VS Code

Install CoAgent8 (okidev.coagent8-mcp) from the VS Code Marketplace, or download coagent8-mcp-0.7.0.vsix from the GitHub release and run Extensions: Install from VSIX.... Then:

1. The first start shows one notice with the CLIs it found, or an offer to set them up. CoAgent8: Manage Coding CLIs installs or signs in a CLI at any time.

2. CoAgent8 is registered in your user MCP servers (mcp.json) and appears in MCP: List Servers; start it there, accept VS Code's trust prompt, and enable its tools in your chat.

3. Ask your agent, for example: "Use CoAgent8 doctor with scope health", "Ask CoAgent8 for a second opinion on this plan" or "Have CoAgent8 review my uncommitted changes".

To use CoAgent8 also inside the CLIs' own chats, choose Add CoAgent8 to All CLI Chats (or Add CoAgent8 to Its Chat in one CLI's menu) in CoAgent8: Manage Coding CLIs.

Codex, Claude Code and Antigravity CLIs

One command registers CoAgent8 in the chats of the CLIs you choose and installs its skills:

npx -y coagent8@next setup --clients=codex,claude,agy

Setup copies the server to ~/.coagent8/runtime/, so the registration does not depend on the npx cache, and keeps a private backup of every file it changes. status checks the CLIs. repair checks the registrations and updates the ones setup wrote and you did not change; an entry you edited is kept. cleanup shows what it would remove; run it again with the --apply=<token> it prints to remove the registrations and skills setup added. npm runs no script on uninstall, so run cleanup before npm uninstall -g coagent8.

Any other MCP host

Add a stdio server to the host's MCP configuration:

{
  "mcpServers": {
    "coagent8": {
      "command": "npx",
      "args": ["-y", "coagent8@next", "mcp"]
    }
  }
}

On Windows, a host that starts commands without a shell may need "command": "cmd" and "args": ["/c", "npx", "-y", "coagent8@next", "mcp"]. coagent8 mcp starts the server; run in a terminal without arguments, coagent8 shows help. Older entries without mcp keep working, because coagent8 and coagent8-mcp still start the server when a host pipes their standard input. coagent8@0.7.0 pins a version. Plain coagent8 (npm latest) is not a supported channel before 1.0.0.

A host with its own tool deadline can stop a long review early. For Codex, set tool_timeout_sec = 1800 in [mcp_servers.coagent8] (setup does this). Continue supports stdio MCP in Agent mode through the same definition, following Continue's MCP guide.

Features

• One MCP server, three coding CLIs. Codex, Claude Code and Antigravity behind the same seven tools, for any stdio MCP host.

• Read-only profiles. Every backend runs in a read-only profile; for Codex and Claude Code CoAgent8 verifies it and refuses a turn it cannot confirm.

• Second opinion and independent review. consult answers a question; review checks Git changes and derives a READY or BLOCKED verdict itself instead of trusting the model's word.

• You decide on expensive models. A model priced high or unknown runs only after you approve it in a form; the calling agent cannot approve it for you. A call can also set a strict price limit.

• Sessions you can continue. A follow-up with the session handle keeps the other agent's context; history is paged and scoped to the workspace.

• Quiet, bounded processes. No shell, no console windows, only processes CoAgent8 started, bounded buffers and one deadline for the whole call.

• Self-diagnosing. doctor lists models, efforts and prices and checks installation, sign-in and quota; issue prepares a sanitized bug report.

• Skills and editor integration. One skill per function for each CLI's chat; the VS Code extension manages CLIs, skills and model approvals.

Backends and read-only profiles

Routing

• backend: auto (default), codex, claude, agy or smart_quota. A model name alone also chooses its backend.

• config.json can fix a default backend or select the smart_quota strategy, limited by allowedBackends.

• auto uses the configured default backend when it is eligible. Otherwise it skips backends with an observed rate limit, prefers a CLI other than the one calling, and ranks the rest by measured quota headroom. A measurement older than 15 minutes counts as unmeasured; doctor with scope: "health" refreshes it.

• A failed turn is never silently retried on another backend.

Models, prices and approval

• A turn uses the call's model, then the session's model, then backends.<id>.defaultModel, then the CLI's own default. CoAgent8 itself names no model.

• reasoning_effort: none, minimal, low, medium, high, xhigh or max, checked against the model's accepted efforts where the CLI lists them.

• Prices come from OpenRouter's public model list (no key, no user data) or from coagent8_PRICES_URL. They decide whether to ask; they are not a bill.

• Your rules in governance.models come first: deny never runs a model, ask asks before every turn, allow runs it without asking (deny wins over ask, ask over allow). Any other model asks when its price is unknown or approximate, at or above governance.askAbovePrice (default 20 USD per million output tokens), or at least governance.priceMultiplier (default 2) times the backend's default.

Review gate

• Scopes: uncommitted (default), staged, a commit, a branch or a range, with optional review instructions. Git context is bounded (4 MiB per Git command, 3 MiB snapshot). From 0.8.0, a diff above 200,000 characters is reviewed in parts, each in its own session, then in one turn over all their findings; above 15 parts the review is refused and you narrow the scope.

• From 0.8.0, checks, such as npm test, are run by CoAgent8 on the reviewed change before the turn, and a check that does not pass blocks the verdict. The reviewing agent itself stays read-only, but the checks run with your account, outside any sandbox, and execute the code under review. A check runs only with your approval: list it in allowedChecks of the configuration, or approve it on the form.

• The reviewing agent answers in a fixed format: snapshot, coverage, verdict, findings as [P1|P2|P3] file:line, and the checks it ran.

• CoAgent8 derives the verdict: an incomplete answer, partial coverage, truncated input, another snapshot, a [P1] or [P2] finding, or a failed check makes it BLOCKED (reason); a workspace change during the turn is reported only when the snapshot or its completeness changed.

• A review of unchanged code with the same scope, backend and model starts no new turn and returns the earlier verdict.

• Staged, commit and range scopes are reviewed only when their files match the current workspace; otherwise review the uncommitted changes.

Sessions and history

• Sessions belong to one workspace and one backend; a follow-up through session_handle keeps the session's model and effort.

• session with action: "history" pages events with cursor and limit (up to 100 events and 240 KiB per page). Each event's sequence is its position in the stored log, so gaps where streaming deltas were combined do not mean lost events, and activePid identifies the CoAgent8 server process owning the active turn. MCP resources coagent8://sessions and coagent8://sessions/{id}/history show the connection's workspace only.

• A session handle expires after two hours without use; a closed session reports that it is closed on a follow-up or cancel, while its history stays readable until deleted. The history archive is best effort: up to 10 MiB per session and 100 MiB in total, old archives removed after seven days. coagent8_HISTORY=off turns archive files off. Private reasoning and raw tool output are never archived or returned.

Safety and bounds

• shell: false; prompts go through stdin, at most 4 MiB.

• Cancellation and deadlines interrupt Codex and Claude Code through their own protocol, then stop only the process CoAgent8 started (Windows: its handle; POSIX: its process group). Nothing is selected by process ID or name.

• Output is bounded: 512 KiB per backend stream, 1 MiB per answer.

• timeout_ms from 100 ms to 30 minutes (default 15 minutes) covers Git, preparation, approval, the turn and teardown, with progress notifications.

• Answers and archives are redacted for credential formats; diagnostics also hide keyword values and home-directory paths. Errors carry a typed code such as CLI_NOT_FOUND, AUTH_REQUIRED, MODEL_UNAVAILABLE, RATE_LIMITED, TIMEOUT, POLICY_DENIED or PRICE_LIMIT.

Tools

A consultation can be as small as:

{
  "proposal": "Is this retry loop safe with concurrent writers? <code>",
  "backend": "codex"
}

context_files passes paths for the other agent to read, not file contents. Results are Markdown: the answer or a typed error, then the backend, model, duration and session_handle=<handle> (<state>). Pass that handle for a follow-up on the same topic; a call without it starts a fresh agent that rereads everything. review adds its verdict.

The deprecated analyze, debug and implement aliases and the run gateway still work but are not listed. Every client receives the same seven tools.

From 0.8.0, delegate needs a Git work tree and, on Windows, the job helper the package carries. Codex writes only inside the workspace (its sandbox, without network access); Claude Code's Edit and Write are limited to the workspace but its Bash is not; Antigravity runs without its sandbox and without a path limit, and only edits files (it runs no commands). Antigravity can end its turn when it reads a file in another checkout, such as the main checkout of a Git worktree (observed with agy 1.4.12). CoAgent8 then retries once inside the workspace, and if that also fails, names the denied action. The agent reports each check as PASS, FAIL or NOT_RUN. Codex on Windows cannot run test runners that start processes from Node, such as node --test, Jest or Vitest. With loop: true CoAgent8 runs the checks itself after the agent, with your account and outside any sandbox, then gets an independent review on a backend other than the agent's (and other than your client's CLI while one remains) and returns failures to the agent for up to two fix rounds; the checks need your approval as in reviews. Without the loop, run the checks yourself before accepting the change. On Windows a cancelled agent's child processes end with it; partial changes stay, so check git status after a cancel or timeout.

Agents can work side by side. Every asynchronous delegate belongs to a root and returns its root_handle; pass it to the next call to share the limits, which come from rootLimits in your configuration (maxCalls 64, maxConcurrent 8, maxChildren 16, maxDepth 3, maxMinutes 240) and which a calling agent cannot raise. At a limit the call fails with ROOT_LIMIT. parent_task records which task a new one follows from. session with action: root shows the use and the tasks; a finished agent does not make the work accepted. A scope is an agreement that the server checks at the start and observes at the end, not a sandbox: an agent can still reach another agent's paths (only Claude Code's Edit and Write are held to the scope, unless a scope entry contains a pattern character such as * or [), a path another agent held is marked as possibly changed by either, and a check an agent runs sees the half-finished work of the others. Roots belong to a CoAgent8 data directory: a client with another one does not see them.

Codex or Claude Code can also coordinate workers on Codex or Claude Code (agy takes no part: it can start subagents that no limit sees). delegate with coordinate: true gives the agent an objective; it reads the workspace in read-only turns and ends each turn by asking for workers or by finishing. CoAgent8 checks each request, runs the workers under the coordinator's root, with scopes inside its scope (an agreement, as above, not a sandbox), waits for all of them and resumes it with their reports. It has no CoAgent8 tools and cannot name a root, a parent or a session. Workers cannot ask you anything: a model that needs your approval, or a check the server would run in a worker's loop that is not in allowedChecks, is refused and reported to the coordinator. Without loop, checks are only an instruction to the worker, under its own profile. Cancelling the coordinator's session or its root stops its workers. After a server restart nothing starts by itself: delegate with coordinate: true and its session_handle tells it what became of each worker. Its final report and its workers' changes are still yours to check.

Approving expensive models

The approval is a form CoAgent8 sends through MCP elicitation; your client must show it to you. Clients that cannot show MCP forms close or decline it without showing it: headless clients, Codex (0.160.1 and 0.164), the Antigravity chat and Claude Code 2.1.317 in VS Code did so when measured. CoAgent8 then says the client answered, not you. CoAgent8 never accepts an approval relayed by the calling agent, so there the turn fails with POLICY_DENIED. To use such a model anyway, allow it with CoAgent8: Manage Model Approvals in VS Code or in governance.models.allow, or call it from a client that shows MCP forms.

Choosing a model under a price limit

Pass the user's limit as output_price_below, in USD per million output tokens. It is strict: 5 means below 5. Without model, CoAgent8 chooses the backend's default if it qualifies, otherwise the most recently released qualifying model (then higher price, then catalog order; undated models rank last):

{
  "proposal": "Calculate 17 * 23. Reply only with the result.",
  "output_price_below": 5
}

Only an exact price from a list younger than seven days qualifies. If no model qualifies, the call fails with PRICE_LIMIT and each backend's reason instead of running another model; an explicit model over the limit is never replaced. The footer states the price, its list and date. A model within the limit may still need your approval.

Every result also shows the tokens the turn used, as the backend reported them, and what they cost at list price when every count and the model's exact price are known: Usage: 12,400 input (9,600 cached) - 900 output (300 reasoning) tokens - list price ~0.014 USD (openrouter 2026-10-19). Unknown counts are left out, never shown as zero. Cache writes are priced by how long they are kept; agy reports no cache counts, and a turn whose input reached a size the list prices differently (such as 272,000 tokens for some OpenAI models) shows counts only. A list price is not your bill: a subscription CLI may charge nothing per token.

To choose yourself, call doctor: it lists each backend's models with their accepted efforts, output price (~ approximate, ? unknown), default and approval tag (ask: <rule>, deny or allow). CoAgent8: Manage Model Approvals in VS Code and npx -y coagent8@next models (coagent8 models when installed globally) show the same list. Then name the model and an accepted effort:

{
  "proposal": "Calculate 17 * 23. Reply only with the result.",
  "model": "<model ID from doctor>",
  "reasoning_effort": "low",
  "output_price_below": 5
}

Skills

Setup and the VS Code extension install one skill per function into each CLI where CoAgent8 is registered. Codex lists them in /skills and runs them as $coagent8-review; Claude Code and the Antigravity CLI offer them as /coagent8-review commands.

CoAgent8: Manage Skills in VS Code and npx -y coagent8@next skills (coagent8 skills when installed globally) in a terminal install, update, uninstall, enable or disable one or all skills per client. Your choices are kept, so repair does not bring back a skill you removed. Disabled skills move to ~/.coagent8/disabled-skills/<client>/. A skill you edited is never overwritten. Start a new chat to see changes. VS Code chat also reads ~/.claude/skills/ and ~/.agents/skills/, so with both Claude Code and Codex set up it lists each skill twice.

npx -y coagent8@next skills status --clients=agy
npx -y coagent8@next skills install --clients=agy --skills=coagent8-review

Changes are shown as a preview first; repeat the command for one client with --apply=<token> to apply them.

VS Code extension

Press F1 (or Ctrl+Shift+P, Cmd+Shift+P on macOS), type CoAgent8 and choose a command:

The extension changes only what you choose, keeps private backups of the CLIs' configuration files, and removes only entries it wrote and that you did not change. When VS Code offers Restart Extensions after an install, update or chat change, use it. VS Code restarts the CoAgent8 server by itself when its settings or bundle change. Settings you save in VS Code take precedence over config.json, except an empty model, which keeps the file's model; the CLIs and other hosts read only the file.

Uninstalling the extension removes what it added: its chat entries, skills, runtime copies and storage, including its sessions and history. Your shared ~/.coagent8/config.json, credentials and the CLIs stay.

Configuration

~/.coagent8/config.json is shared by every host, the CLI and the VS Code extension. Without the file the defaults apply. An unreadable or invalid file stops execution with POLICY_DENIED while doctor keeps working.

{
  "schemaVersion": 1,
  "defaultBackend": null,
  "routing": {
    "strategy": "fixed",
    "allowedBackends": ["codex", "claude", "agy"]
  },
  "backends": {
    "agy": { "executable": "vscode-extension", "defaultModel": "<model the first doctor recorded>" }
  },
  "governance": {
    "priceMultiplier": 2,
    "askAbovePrice": 20,
    "models": { "allow": [], "ask": [], "deny": [] }
  }
}

A backend's CLI is backends.<id>.executable when it is set (an absolute path, ~/..., or vscode-extension for the vendor extension's copy); a configured CLI that is missing fails instead of falling back. Without it, the CLI is found on PATH, then in the vendor's VS Code extension. The workspace comes from workspace_path, the client's roots, or the server's working directory.

The architecture states every contract, bound and error.

Known limitations

• Antigravity's own tools. agy gives the other agent your agy MCP servers and plugins, which CoAgent8 cannot turn off; doctor lists them. Calls back into CoAgent8 are refused.

• Antigravity readiness. agy may report not ready in a cached check and still run a turn; doctor with scope: "health" rechecks readiness.

• Leftover agy processes on Windows. Cancelling or timing out an agy turn stops agy itself, but a process agy started outside it, such as one of its MCP servers, can keep running until it exits or the CoAgent8 server stops.

• Parent crash on macOS and Linux. If the host dies unexpectedly, the processes CoAgent8 started are not cleaned up.

• Default model price. A plain consult with no model and no price limit runs the backend's default model (still subject to your approval thresholds); pass output_price_below or a model to bound the price.

• Approval forms. Clients that cannot show MCP forms cannot approve an expensive model (see approving expensive models) or the checks of delegate with loop: true. Claude Code 2.1.317 in VS Code and Codex 0.164 did not show the check form when measured, so list the exact commands in allowedChecks of the CoAgent8 configuration instead.

• Host deadlines. A host can stop a tool call before CoAgent8's own deadline; a headless agy client stopped calls after 180 seconds.

• Sessions on disk. Every call keeps a session record, even with archives turned off, and the session handle arrives with the result.

• Codex sandbox on Windows. CoAgent8 runs Codex in its unelevated Windows sandbox, which reads what your account can read and blocks writes. A PowerShell installed from the Microsoft Store cannot start inside it, so Codex falls back to Windows PowerShell 5.1; install PowerShell 7 another way (for example scoop install pwsh or the MSI) to give Codex version 7.

• Reviews of another tree. A staged, commit or range review whose files do not match the current workspace is refused rather than reviewed.

Reporting problems

For suspected security vulnerabilities, follow the security policy and report privately. Do not include vulnerability details in public issues.

Ask your agent to run the issue tool: it prepares a sanitized report with your OS, Node and detected CLI versions (when include_doctor is true, the default; no readiness or quota) and a link that opens a new GitHub issue with it. Add the steps and what you expected, and check the text for private data before you submit it. You can also use the bug-report form directly: only "What happened" is required.

Building and contributing

Building from source needs Node.js 24.11+ or 26+:

npm ci
npm run build

The server is then node <checkout>/dist/index.cjs; npm pack produces the installable package. A checkout of develop is a development build, not a release. Restart a running MCP server after rebuilding.

The npm package does not include docs/ or the contributor rules; these links work in the repository.

License

Copyright (c) 2026 Oktawian Wybieralski (oki.dev).

The project source, documentation and artwork in this checkout are licensed under the MIT License. See LICENSE for the terms and warranty disclaimer. Bundled dependencies retain their own licenses and notices in dist/THIRD_PARTY_NOTICES.txt.

0.6.1 is the first release under the MIT License. Copies of published 0.6.0 and the withdrawn npm version 1.0.0-beta.1 retain their GPL-3.0-only permissions. This change does not revoke any license previously granted for a distributed copy.

Trademarks. CoAgent8 and the CoAgent8 logo are trademarks of Oktawian Wybieralski (oki.dev). The copyright licenses under which CoAgent8 is or was distributed cover the software, documentation and artwork, including the logo files, and this notice does not limit them. They do not grant rights to use the name or logo as a trademark, for example to brand a modified version or another distribution, or to suggest endorsement. Accurate references to CoAgent8, such as naming it as the origin of a fork or describing compatibility, need no permission.

Created by Oktawian Wybieralski - GitHub repository