Skip to main content
Glama

agy-handoff

Codex, Claude Code, and Antigravity review a change from age >= 18 to age > 18 in parallel. The combined report flags that age 18 is now rejected at age.js:8.

Use Antigravity, Claude Code, or Codex to delegate a focused task, review changes independently, or compare implementation plans. All three integrations use the same local MCP server, CLI runners, settings, and job format. The active session verifies the results and writes the final synthesis.

Install

Use Node.js 18.18 or later. Install and sign in to the external CLIs you want to use. The runner minimums are Codex 0.160.0, Claude Code 2.1.259, and Antigravity 1.5.0. Keep your main harness on a current release with plugin support.

git clone https://github.com/CourageHW/agy-handoff.git

Antigravity · agy-handoff

agy plugin install ./agy-handoff

Open Antigravity in the target repository and run these commands.

/agy-handoff:handoff-doctor
/agy-handoff:handoff-cross-review Review my uncommitted changes.

The installed Antigravity plugin keeps its original three-engine cross-review and planning defaults. Its three subagents remain available in Antigravity CLI. Use /agents to inspect an individual subagent run. To review with only Codex and Claude Code, say “Ask the other two agents to review my changes.” For removal, run agy plugin uninstall agy-handoff. Antigravity plugin docs

Claude Code · claude-handoff

cd agy-handoff
npm run package:integrations
claude plugin marketplace add ./dist/handoff-plugins
claude plugin install handoff-bridge@agy-handoff

Start Claude Code in the target repository. Use /mcp to check the connection. The native plugin ID is handoff-bridge because Claude Code reserves the claude- prefix.

/handoff-bridge:handoff-doctor
/handoff-bridge:handoff-cross-review Ask the other two agents to review my changes.
/handoff-bridge:handoff-delegate Delegate debugging this failing test to Codex.

Claude Code defaults to Codex and Antigravity for cross-review and planning. You can also load the bundle for a single session with claude --plugin-dir /absolute/path/to/dist/handoff-plugins/plugins/claude-handoff. For removal, run claude plugin uninstall handoff-bridge@agy-handoff and optionally claude plugin marketplace remove agy-handoff. Claude Code plugin manifest · Claude Code skills

Codex · codex-handoff

cd agy-handoff
npm run package:integrations
codex plugin marketplace add ./dist/handoff-plugins
codex plugin add codex-handoff@agy-handoff

Start Codex in the target repository. Select the bundled skill using $ or ask in natural language. Approve the requested handoff in Codex if prompted. Use a local session with interactive approvals when a tool requires approval.

$handoff-doctor
$handoff-cross-review Ask the other two agents to review my changes.
$handoff-plan Compare implementation proposals for this feature.

Codex defaults to Claude Code and Antigravity for cross-review and planning. Use /mcp to check the connection. For removal, run codex plugin remove codex-handoff@agy-handoff and optionally codex plugin marketplace remove agy-handoff. Codex plugin packaging and MCP policy · Codex skills

After pulling updates, rebuild the local marketplace and reinstall its plugins to refresh the cached packages.

Related MCP server: switchboard

Review, plan, and delegate

Skill

Example request

handoff-review

Get an independent second opinion from Antigravity on this diff.

handoff-cross-review

Ask the other two agents to review my changes or compare the proposed implementations.

handoff-grill-me

Work through open design questions before writing a plan.

handoff-plan

Create a collaborative implementation plan with file targets and tests.

handoff-delegate

Ask Codex to trace this failing test. Include the failing command and relevant files.

handoff-models

Show or change default models and reasoning effort by engine and command.

A single review or delegation accepts an explicit engine or uses engine: "auto". Cross-review and planning accept an explicit engines list, including the main harness's CLI if requested. Existing clients can still use includeAgy to choose the legacy three-engine or Codex-and-Claude roster. Pass the target repository as cwd and scope the request with context.files and context.summary.

Structured results list requested and participating engines, per-engine errors, and the active session as synthesizer. A missing CLI, quota error, timeout, or invalid payload can leave a partial result. The server checks cited files and line numbers and verifies proposed plan targets on disk. Confirm defects by reading the code and checking its behavior before acting on reviewer agreement.

For long single-engine reviews and delegations, use background: true and collect the job ID. Claude Code and Codex use handoff_job_status and handoff_job_result for progress and execution evidence. Use handoff_job_status with includeStats: true and no job ID to see recorded usage. Cross-review and planning stream progress in a single MCP call.

Terminal usage

From the plugin checkout, pass the target repository with --cwd. For example, to review a feature branch against its local main branch, run the following command.

node src/cli.mjs cross-review --cwd ../my-project --scope base --base main --structured

For a focused review, pass the file path and the question you want answered.

node src/cli.mjs review --cwd ../my-project --engine codex --scope custom \
  --files src/jobs.mjs --prompt "Check how failed jobs are retried."

Use node src/cli.mjs watch to follow active jobs and node src/cli.mjs stats --table to see outcomes, duration, and CLI-reported usage. Run node src/cli.mjs --help for other commands. Use --engines codex,claude to choose a roster for cross-review or plan.

Permissions and retries

Reviews and plans run in read-only mode. Delegation defaults to read-only. In Claude Code and Codex, set mode: "workspace-write", confirmWorkspaceWrite: true, and the target cwd only after the user authorizes edits by the external engine. Host approval prompts still apply.

Engine

Read-only

Workspace write

Codex

Codex read-only sandbox

Codex workspace-write sandbox

Claude Code

Restricted file tools and an allowlist of read-only Git commands

File tools are confined to the working directory. Bash runs without an OS sandbox.

Antigravity

--sandbox --mode plan

--sandbox --mode accept-edits

Child sessions cannot initiate another handoff through the MCP tools or Handoff CLI. An identical in-flight request in the same MCP server is rejected. Use the existing job status before submitting another request.

After a failed read-only job, check its status for retryable before calling handoff_job_retry. If a write fails partway through, inspect the working tree before starting another job. On foreground read-only runs, Antigravity can switch from Neon to Argon once if Neon reports a quota error.

Configuration

Run node src/cli.mjs models show to see the active defaults. Auto-routing selects among the active harness's external engines using CLI availability, compatibility, recent failures, and routing preferences. The settings file supports balanced, least-used, prefer-codex, prefer-claude, and prefer-agy. Automatic workspace-write routing excludes Claude Code unless routing.allowUnsandboxedWriteAuto is enabled.

The plugins pass their host explicitly. For a standalone server, use node src/mcp-server.mjs --host claude (or codex / antigravity). Standalone --host antigravity uses the two external engines by default. A bare server invocation keeps the legacy three-engine group roster and Codex/Claude auto-routing.

Environment variable

Purpose

AGY_HANDOFF_CODEX_BIN, AGY_HANDOFF_CLAUDE_BIN, AGY_HANDOFF_AGY_BIN

Set an executable path for one engine. Set AGY_HANDOFF_AGY_BIN=none to disable the Antigravity reviewer.

AGY_HANDOFF_HOST

Select defaults for standalone CLI/MCP sessions. An explicit MCP launch argument takes precedence.

AGY_HANDOFF_CONFIG

Use a different model and routing configuration file.

AGY_HANDOFF_JOBS_DIR

Choose where to store job logs and event streams. Set the same directory in the MCP and terminal environments to inspect the same jobs from both.

Task

Tools

Check the installation or change settings

handoff_doctor, handoff_config

Review, plan, or delegate

handoff_review, handoff_cross_review, handoff_plan, handoff_delegate

Follow a job or retrieve its output

handoff_job_status, handoff_job_result

Cancel a background job or retry an eligible job

handoff_job_cancel, handoff_job_retry

Development

Run npm test for unit and MCP tests with mock CLIs. The CI matrix runs those tests on Linux, macOS, and Windows. Run agy plugin validate --strict . to check the existing Antigravity bundle. After packaging, run claude plugin validate ./dist/handoff-plugins/plugins/claude-handoff to check the Claude Code bundle.

For live checks, use the Quick Start in each host and verify the actual MCP tool call and responding engines. Run npm run test:live for the existing runner smoke suite with installed, authenticated CLIs. A mock pass verifies the local protocol and runner wiring. Live runs also depend on host permissions, CLI versions, authentication, and provider quotas.

Contributing · Changelog · MIT license

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers