Skip to main content
Glama

claude-agy-mcp

An MCP server that lets any agent drive Claude Code and Antigravity (agy) sessions as controlled subagents — list them, start them, talk to them, pause them, switch their model, read their output, and run several at once.

It exists because an agent that can spawn another agent but cannot see it, wait for it, or stop it has not gained a worker; it has gained a race condition.

// mcp config
{
  "mcpServers": {
    "claude-agy": {
      "command": "node",
      "args": ["/absolute/path/to/claude-agy-mcp/bin/claude-agy-mcp.js"]
    }
  }
}

No dependencies. Node >= 20.12. Nothing to install.


The problem it solves

Both harnesses are full-screen TUIs. Claude Code additionally ships a real background-session API (claude --bg, claude agents --json, logs, stop, respawn, rm) and this server prefers it wherever it exists, because a structured API beats scraping a screen. agy has no equivalent, so those sessions are driven through tmux — and the tool says so rather than pretending otherwise.

Claude Code

Antigravity (agy)

background session

yes (--bg, real id, real log)

no

list sessions

agents --json

tmux

send a message

--bg --resume <id>

keystrokes

stop / resume

stop / resume

tmux kill

switch model

next turn

/model in-session

Related MCP server: agentmux

Tools

Inventory

  • agent_list — every session, both harnesses, one table

  • agent_inventory — which binaries exist, their versions, extra installs that could shadow them

  • agent_models — known model ids and effort levels per harness

Read

  • agent_read — recent output, optionally waiting for the agent to stop generating

  • agent_wait_idle — block until output stops changing

  • agent_limits — is a session rate- or usage-limited right now

  • agent_transcript — where the conversation lives on disk

Spawn

  • agent_spawn — one session (background for Claude, tmux for agy)

  • agent_spawn_many — a fan-out, reporting partial failure honestly

Talk

  • agent_send — send, and by default wait for the answer

  • agent_interrupt — stop generation without ending the session

Lifecycle

  • agent_stop, agent_resume, agent_respawn, agent_set_model

Bridge (agents cannot call each other directly; this is the channel that reaches them)

  • bridge_send, bridge_inbox, bridge_status

Self

  • self_openbot — restart the host that is running this tool, after a config change, with no human

Design notes that are load-bearing

Idle detection is movement-based, not marker-based. A "is it busy?" check built on one vendor's status string is one rename away from lying — that has already happened here once, and the failure mode is that a working agent reads as idle. This server watches whether the screen is still changing, and only uses the busy marker as a secondary signal so a long silent think is not mistaken for a finish.

A tool that cannot do the thing says so. agent_spawn for agy with mode=background returns "agy has no background-session mode", not an empty success. A silent no-op is the failure that makes an orchestration layer worthless, because the caller cannot tell it apart from work.

The bridge appends under a lock and fsyncs. It is written by more than one process, and a torn line makes the whole log unparseable. That failure has already destroyed an inbox on this machine.

self_openbot starts the replacement before it retires anything. The new terminal comes up first, and the kill is performed by a detached helper after a delay so the tool result is delivered before the process exits. The command is verified to exist on PATH first — refusing is correct when the alternative is killing the session with nothing to replace it.

Test

node test/smoke.mjs

Speaks the real protocol over a pipe to a real child process: handshake, tools/list, a live inventory read, the bridge, the dry-run path, an unknown tool, and a failing tool call. It exists to catch a server that starts but lists nothing or corrupts stdout — which a unit test against the handlers would never see.

Available Tools

19 tools
agent_interruptA

Stop a tmux-hosted agent mid-generation without killing its session, by sending Escape (then Ctrl-C if asked). The conversation is preserved. Use agent_stop to end the session instead.

Inputs: session (required), hard.

agent_inventoryA

What agent CLIs this machine actually has: the resolved binary path, its version, other installs that could shadow it, and (for agy) its configured MCP servers. Use before spawning so you know which build you are driving.

Inputs: no named parameters.

agent_limitsA

Report whether a session is currently rate- or usage-limited, and the reset time the banner names if so. Reads the live pane rather than a counter, because these notices are rendered into the UI and never returned through any API.

Inputs: session.

agent_listA

List every agent session on this machine in one view: Claude Code background sessions and live tmux sessions (Claude and agy), with harness, state, cwd and a short screen preview. Call this first — every other tool takes an id or name from here.

Inputs: json, kind, harness.

agent_modelsA

Known model ids and effort levels for each harness, plus the paths to change them by hand. Guidance, not a whitelist — the CLIs accept any id.

Inputs: no named parameters.

agent_readA

Read the recent output of a session. For a tmux session this is the screen with TUI chrome stripped; for a Claude background session it is that session's log. Pass wait_idle: true to block until the agent stops producing output first.

Inputs: session (required), lines, wait_idle, idle_timeout_ms.

agent_respawnA

Restart a Claude background session (or all of them) so it picks up the CURRENT Claude binary. Use after claude update, or when a session was started by an older build — a running process keeps the model list it booted with.

Inputs: all, session.

agent_resumeA

Bring a stopped Claude background session back, optionally with a new message. Restarts it in the background under the same id.

Inputs: session (required), message.

agent_sendA

Send a message to an existing session and, unless wait:false, wait for it to finish answering. Wraps the right mechanism per harness: a resumed background turn for Claude background sessions, keystrokes for a tmux session.

Inputs: message (required), session (required), wait, timeout_ms.

agent_set_modelA

Change the model a session runs on. For a running tmux session this types the /model command and confirms the switch, because a live process cannot be re-pointed any other way. For a background session it applies on the next turn.

Inputs: model (required), session (required), effort.

agent_spawnA

Start a new agent session. harness=claude uses Claude Code's native background session (preferred — it has a real id and a real log). harness=agy starts a tmux-hosted Antigravity session, because agy has no background mode. mode=tmux forces an interactive tmux session for either harness.

Inputs: harness (required), cwd, mode, name, +7 more.

agent_spawn_manyA

Start several sessions at once — one per prompt, or N clones of one prompt. Returns the ids it created and any that failed, so a partial fan-out is visible instead of silent.

Inputs: harness (required), cwd, count, model, +5 more.

agent_stopA

Stop a session. Claude background sessions keep their conversation and can be resumed; a tmux session is destroyed (its transcript on disk survives). Says which one it did.

Inputs: session (required), all, remove.

agent_transcriptC

Where a session's conversation is stored on disk, so a caller can read the raw history itself. Resolves the config-dir indirection rather than guessing a path.

Inputs: limit, session.

agent_wait_idleA

Block until a tmux-hosted agent stops producing output. Movement-based, not marker-based, so it works for any harness. Returns as soon as the screen has been stable for a few seconds.

Inputs: session (required), stable_ms, timeout_ms.

bridge_inboxB

Read messages waiting for an agent on the bridge. Defaults to the calling agent's own inbox (opencode).

Inputs: for, limit, mark_read, unread_only.

bridge_sendA

Send a message to another agent through the file-backed bridge (Claude Code and agy cannot call each other directly, and this is the channel that reaches them). A watcher wakes the other side, so this is how you hand off or ask for help.

Inputs: to (required), content (required), from, subject, +2 more.

bridge_statusA

The bridge file's location, size, and which agent pairs are actually talking. Use it to check a channel exists before relying on it.

Inputs: limit, history_with.

self_openbotA

Restart the agent host that is running this tool: opens a NEW terminal running the agent first, then retires the current process a few seconds later. Use after changing config, plugins or MCP servers that only take effect on restart — no human needed. Refuses if the replacement command is not on PATH, because killing the session with nothing to replace it is not recoverable through this channel.

Inputs: cwd, delay, command, dry_run.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have distinct purposes (inventory vs list vs models, spawn vs spawn_many, stop vs interrupt vs respawn), and descriptions explicitly cross-reference each other to disambiguate. The only mild overlaps are agent_read with wait_idle versus agent_wait_idle, and agent_send versus bridge_send, but the channel distinction is explained.

    Naming Consistency5/5

    Every tool is snake_case with a clear namespace prefix (agent_, bridge_, self_) grouping related operations. The verb_noun pattern is consistent throughout (agent_spawn, agent_read, bridge_send, bridge_status).

    Tool Count4/5

    19 tools is on the heavier side but each covers a genuine operation across session lifecycle, bridge messaging, and self-management. Nothing is obviously redundant, though it sits near the upper bound for comfortable scoping.

    Completeness4/5

    The session lifecycle is well covered (inventory, list, spawn, read, send, interrupt, stop, resume, respawn, set_model, wait_idle, limits, transcript) plus a bridge channel and self-restart. Minor gaps like session cleanup or bulk stop exist, but core workflows have no dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an interactive Claude Code session to delegate blocking tasks to headless pi and OpenCode workers, and lets all three peers exchange messages and list paired sessions over a shared local file bus. It exposes 18 tools covering sync/async asks, steering, abort, session lifecycle, state inspection, and cross-agent messaging.
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables any MCP host to delegate work to multiple coding-agent CLIs such as Codex, Claude Code, and Antigravity as subagents, preserving native sessions and supporting team-based supervision and agent-to-agent messaging.
      17
      11 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to delegate work to nested subagents running on Codex and Claude Code, keeping each task's session, turn history and results durable in SQLite while the main chat continues. Supports async or blocking waits, mid-session context updates, git worktree isolation, read-only-by-default permission inheritance, and cancelling whole subagent trees.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables a lead AI agent to spawn and coordinate manager agents, which can in turn run child agents across Codex/ChatGPT, Google Antigravity, Claude Code, and local OpenAI-compatible models. Provides messaging, waiting, transcripts, file exchange, and saved-conversation adoption so multi-agent workflows can be orchestrated from MCP hosts.
      14
      MIT