handoff-mcp

An MCP server (and matching CLI) that lets Claude hand a task off to a peer coding-agent CLI — OpenAI's Codex or Google's Antigravity (Gemini 3) — and get the answer back inline.

Why you'd want this:

• Independent second / adversarial opinion. Get a genuinely different model to poke holes in a proof, design, diff, or argument instead of Claude reviewing its own work.
• Separate quota pools. Codex runs on your OpenAI/ChatGPT subscription; Antigravity runs on your Google AI Pro subscription. Handing work off preserves your Claude usage limit at no extra cost — the two peers don't touch each other's quota or Claude's.
• Visual feedback. Antigravity/Gemini 3 is natively multimodal — attach a screenshot, diagram, chart, or PDF and ask what's wrong with it.
• Async status. Fire a long handoff as a background job and poll it; you see the peer agent's progress stream in rather than blocking on one long call.

Be aggressive about handing off when your Claude usage limit is near. The server's tool docs instruct the calling model to lower its bar for delegating when the Claude/Fable limit is close — bulk review, long reads, second opinions, and mechanical agentic coding are all good candidates.

---

Backends — who's good at what

The routing guidance below is verified as of 2026-07-21. The model landscape moves fast; see Maintenance.

	codex (codex exec)	antigravity (agy)
Model	OpenAI GPT-5.x-Codex	Google Gemini 3 Pro
Quota	OpenAI / ChatGPT subscription	Google AI Pro subscription
Best at	agentic/terminal coding (Terminal-Bench ~77% vs ~54%), long-horizon autonomous work, large refactors & migrations, adversarial code review, bug hunting, long-context reliability	visual feedback (screenshots, diagrams, PDFs), very long context (1M–2M tokens: whole monorepos / long docs), novel reasoning, cheap bulk work
Weak at	images / diagrams / UI (text-specialized); Codex surface caps context ~400K	terminal-agentic coding; the agy CLI is finicky headless (worked around here)
Attachments	text + images	text + images + PDFs

Rule of thumb: code / agentic / second-opinion-on-text → codex. Anything visual, or too large for a normal context window → antigravity.

Note: Google retired the open-source gemini CLI for individual accounts on 2026-06-18 (IneligibleTierError); Pro/Ultra/free users are served by Antigravity now. That's why the Google backend here is agy, not gemini.

---

Tools

Tool	Purpose
handoff	Run a backend synchronously, return its answer.
handoff_start	Fire a background job, return a job id immediately.
handoff_status	Poll a job: state, elapsed_s, streamed log_tail, result.
handoff_jobs	List recent jobs.
handoff_backends	Install/auth readiness of each backend + a guidance-staleness banner.
handoff_guidance	The full model routing guide.

handoff(prompt, backend, files=[], model="", cwd=None, approve=False, timeout=600)

• prompt — self-contained instruction. The peer has none of your conversation's context.
• backend — "codex" or "antigravity".
• files — absolute/~ paths. codex: text + images. antigravity: text, images, PDFs. Attachments are copied into a throwaway temp workspace — originals are never touched.
• model — optional id override; empty = the CLI's own default.
• cwd — a project dir the peer may read for extra context (never written unless approve=True).
• approve — allow the peer to make edits (codex workspace-write; antigravity accept-edits). Default False = read-only, right for reviews/opinions.
• timeout — seconds before abort.

Async pattern

job = handoff_start("deep-review this repo for races", "codex", cwd="~/proj")
# → "Started codex job a1b2c3…"
handoff_status("a1b2c3…")   # poll until state != "running"

---

Setup

1. Install the peer CLIs

Codex (OpenAI):

brew install codex        # or: npm i -g @openai/codex
codex login               # sign in with your ChatGPT account
codex login status        # → "Logged in using ChatGPT"

Antigravity (Google):

brew install --cask antigravity-cli
agy                       # run once, sign in with your Google (Pro) account, then quit

2. Install this server

uv tool install --force ~/Documents/programming/handoff-mcp

Installs both the handoff CLI and the handoff-mcp server onto your PATH.

3. Register the MCP server with Claude Code

claude mcp add handoff -- handoff-mcp

Check everything's wired up:

handoff --status      # backend install/auth + guidance freshness
handoff --guidance    # the routing guide

---

CLI usage

# adversarial code review
handoff codex "review this for correctness and edge cases" -f src/core.py

# visual feedback
handoff antigravity "what's wrong with this dashboard layout?" -f screenshot.png

# read something huge
handoff antigravity "summarize the key obligations in this contract" -f contract.pdf

# let a peer explore a whole repo (read-only)
handoff codex "is there a race condition in the job queue?" -C ~/Documents/programming/myproj

# actually let it edit (opt-in)
handoff codex "migrate this file to async/await" -f app.py --approve

# long job, tail progress until done
handoff codex "find every N+1 query" -C ~/proj --async

# health / guidance
handoff --status
handoff --guidance

---

Configuration (env vars)

Var	Default	Purpose
HANDOFF_CODEX_BIN	codex	Path/name of the Codex binary.
HANDOFF_AGY_BIN	agy	Path/name of the Antigravity binary.
HANDOFF_MODEL	(empty)	Default model override for both backends.
HANDOFF_TIMEOUT	600	Default sync timeout (seconds).
HANDOFF_JOB_TIMEOUT	1800	Default background-job timeout (seconds).
HANDOFF_MCP_HOME	~/.cache/handoff-mcp	Where job logs live.

---

How it works

All logic lives in src/handoff_mcp/core.py; the MCP server (server.py) and CLI (cli.py) are thin, DRY wrappers.

• Codex is headless-native: we run codex exec --json --skip-git-repo-check -s <sandbox> -o <last-message-file>, stream the JSONL events into a per-job log for status, and read the clean final answer from the -o file. The prompt is fed via stdin (codex's -i/--image flag is variadic and would swallow a trailing positional prompt).
• Antigravity (agy) gates its stdout on isatty() (upstream bug: empty output in a non-TTY). We run it inside a pseudo-terminal and strip the ANSI / spinner noise back out. It also can't prompt for tool permissions headlessly, so we pass --dangerously-skip-permissions (safe: throwaway temp workspace with only file copies) and gate edits with --mode plan (read-only) vs accept-edits.
• Async jobs run on background threads writing to a log file, so handoff_status can return live progress and the final result across successive tool calls.

Maintenance

The strengths/weaknesses and default models reflect the model landscape as of core.MODEL_INFO_UPDATED (2026-07-21). handoff_backends and handoff --status print a staleness banner that escalates to a warning once the guidance is over ~120 days old. When new Gemini / GPT / Codex versions ship, update ROUTING_GUIDE and MODEL_INFO_UPDATED in src/handoff_mcp/core.py.

License

MIT