Agy Headless Bridge

agy-headless-bridge

Call the Google Antigravity CLI (agy) headlessly — and actually get output back.

Codename PtyGravity · pty + antiGravity

[](https://pypi.org/project/agy-headless-bridge/) [](https://pypi.org/project/agy-headless-bridge/) [](https://registry.modelcontextprotocol.io/v0/servers?search=agy-headless-bridge) [](https://github.com/rhishi99/agy-headless-bridge/actions/workflows/test.yml) [](LICENSE) [](https://www.python.org) []()

📖 Architecture & docs → rhishi99.github.io/agy-headless-bridge

---

TL;DR — the problem, before & after

agy -p "" prints nothing when its stdout is not a real terminal. So calling it from a subprocess, an MCP server, CI, or another coding agent (Claude Code, Codex, …) returns an empty string and exit 0 — silently. This package gives agy a fresh pseudo-terminal so it emits normally, then cleans the output.

flowchart TB
    subgraph B["❌ BEFORE — agy -p from any non-TTY caller"]
        direction TB
        a1["subprocess · MCP · CI · agent"] --> a2["agy -p "prompt""]
        a2 --> a3["stdout gated by isatty()"]
        a3 --> a4["(empty string)exit 0 · no error · no output"]
    end
    subgraph A["✅ AFTER — through agy-headless-bridge"]
        direction TB
        b1["subprocess · MCP · CI · agent"] --> b2["run(prompt)"]
        b2 --> b3["allocate fresh pseudo-terminal"]
        b3 --> b4["agy -p "prompt"isatty() == True"]
        b4 --> b5["clean() strips ANSI/TUI"]
        b5 --> b6["clean text ✓"]
    end

    classDef bad fill:#2a1313,stroke:#f87171,color:#ffd9d9;
    classDef good fill:#0f2a1e,stroke:#34d399,color:#d7ffe9;
    class a1,a2,a3,a4 bad;
    class b1,b2,b3,b4,b5,b6 good;

# ❌ The problem — plain subprocess
import subprocess
r = subprocess.run(["agy", "-p", "say hi"], capture_output=True, text=True)
print(r.stdout)          # '' — prints nothing, exit 0

# ✅ The fix
from agy_headless_bridge import run
print(run("say hi"))     # 'Hi! How can I help?'

Three entry points around one core:

| Entry point | Invoke | Use for | |---|---|---| | Library | from agy_headless_bridge import run | embedding agy in Python | | CLI | agy-bridge "prompt" | shell scripts, quick calls | | MCP server | python -m agy_headless_bridge.mcp_server | letting an agent call agy as a tool |

---

The problem in detail — upstream bug [#76]

agy gates its stdout on isatty(). The instant stdout isn't a terminal, it goes silent — no output, no error, exit 0:

$ agy -p "say hi" | cat
$            # empty. exit 0. nothing.

The common winpty agy -p "..." workaround needs a terminal that already exists, so it still fails from any automated / non-TTY caller.

The fix — give agy a tty it didn't ask for

Allocate a brand-new pseudo-terminal (one that needs no parent tty) and attach agy to it. Same code path on every OS — only the pty allocator differs.

flowchart TD
    A["Caller — non-TTYClaude Code · MCP · subprocess · CI"] -->|"prompt"| B{{"run(prompt)"}}
    B --> C["find_agy()$AGY_PATH → PATH → OS defaults"]
    C --> D{"sys.platform?"}
    D -->|"win32"| E["pywinptyPtyProcess.spawn"]
    D -->|"posix"| F["stdlib ptyos.openpty + Popen"]
    E --> G(["fresh pseudo-terminal"])
    F --> G
    G --> H["agy -p promptisatty == True → emits"]
    H -->|"raw bytes + ANSI/TUI chrome"| I["clean()strip CSI/OSC · collapse \r repaints · drop spinner glyphs"]
    I -->|"clean text"| A

| Platform | pty backend | Status | |---|---|---| | Windows | ConPTY via [pywinpty] (PtyProcess) | ✅ verified (agy 1.0.6) | | Linux / macOS | stdlib [pty] (os.openpty + subprocess.Popen) | ✅ verified on macOS hardware |

> [!TIP] > Linux users wanted. The pty mechanics are verified on Linux CI and macOS hardware, but the real agy round-trip on bare-metal Linux hasn't been run. > If you're on Linux: pip install agy-headless-bridge, try it, and > tell us how it went — pass or fail. PRs welcome.

> Why not just the existing agy Claude Code plugins? They wrap agy for > triggering (slash commands, model selection) but still call agy -p > directly — so in any headless context they hit this exact empty-output bug. > This package fixes the I/O layer they're missing. Use both together.

---

Prerequisites

Before installing this bridge you need:

1. Python 3.9+ — python --version.
2. The Antigravity CLI (agy), installed and authenticated:

• Install:
• Authenticate once interactively (agy opens a browser OAuth flow), or set

ANTIGRAVITY_API_KEY in your environment if you use an API key.

• Verify it runs in a real terminal: agy -p "say hi" should print a reply.

(From a pipe it won't — that's the very bug this package fixes.)

1. Windows only: pywinpty (installed automatically as a dependency).

POSIX uses the stdlib pty module — nothing extra.

> This package does not install or authenticate agy, and does not bundle > any credentials. It only spawns the agy already on your machine.

---

Install

Requires Python 3.9+.

pip install agy-headless-bridge          # pywinpty auto-installs on Windows only

From source:

git clone https://github.com/rhishi99/agy-headless-bridge
cd agy-headless-bridge
pip install -e .

The bridge locates the binary via, in order: $AGY_PATH → agy on PATH → OS default install paths.

---

Usage

Library

from agy_headless_bridge import run, AgyNotFoundError, AgyTimeoutError

try:
    # For a CODING task, pass the repo so agy can see it — the library `run()`
    # is a thin primitive and does NOT auto-add a workspace (the CLI/MCP layers
    # do). Without add_dirs, agy -p runs blind in its own scratch workspace.
    print(run("Summarize this repo", add_dirs=["."], timeout=600))
except AgyTimeoutError as exc:
    print("timed out; partial so far:\n", exc.partial)  # resume with `agy -c`
except AgyNotFoundError:
    print("install agy first")

run(prompt, timeout=900, agy_path=None, *, add_dirs=None, model=None, idle_timeout=120, extra_args=None) -> str — raises AgyNotFoundError if the binary is missing, AgyTimeoutError (carrying .partial) on the idle or hard timeout, ValueError on empty prompt. Returns "" only if agy genuinely emitted nothing. add_dirs → agy --add-dir; model → --model. The timeout is the absolute ceiling; idle_timeout ends a run that has gone silent for that many seconds (so a long-but-active task survives the ceiling).

To get the CLI/MCP "default to cwd for coding, none for research" behaviour in your own code, use resolve_add_dirs(explicit, use_cwd_default=...).

CLI

agy-bridge "reply with exactly: OK"
python -m agy_headless_bridge "reply with exactly: OK"   # equivalent

# Coding task: the current directory is auto-added to agy's workspace, so agy
# sees your repo with no extra flags.
agy-bridge "Find and fix the off-by-one in the parser"

# Research / Q&A that needs no repo — opt out of the cwd default:
agy-bridge --no-workspace "Explain idle timeouts in process supervision"

# Add more dirs, pick a model, widen the limits for a big task:
agy-bridge --add-dir ../shared-lib --model gemini-3-pro \
    --timeout 1800 --idle-timeout 180 "Refactor X to match the shared lib"

| Flag | Default | Meaning | |---|---|---| | --add-dir DIR | cwd (auto) | Add a dir to agy's workspace (repeatable). | | --no-workspace | off | Don't auto-add cwd (use for research / Q&A). | | --model NAME | agy default | agy --model. | | --timeout SECS | 900 | Hard ceiling (absolute wall). | | --idle-timeout SECS | 120 | Kill after this many seconds of no output. |

MCP server

claude mcp add --transport stdio antigravity -- \
    python -m agy_headless_bridge.mcp_server

> Windows: use py -3.11 (the [Python Launcher]) instead of python in the > command above. Bare python can resolve to the wrong interpreter or the > Windows Store stub, which surfaces as an -32000 MCP connection error. See > [Troubleshooting](#troubleshooting--faq).

The server speaks JSON-RPC stdio directly (no MCP SDK dependency) and routes every call through the pty bridge.

Tool schema (what an agent — or you, integrating manually — sees):

| Tool | Argument | Type | Required | Description | |---|---|---|---|---| | agy_ask | prompt | string | ✅ | one-shot prompt sent to agy | | agy_ask | workspace | "auto"\|"none" | | auto (default) adds the server's cwd so agy sees the repo; none for research / Q&A | | agy_ask | add_dir | string[] | | explicit dirs for agy's workspace (overrides the workspace default) | | agy_ask | model | string | | agy --model | | agy_ask | timeout | number | | hard timeout override, seconds | | agy_research | query | string | ✅ | wrapped as a deep-research prompt for agy (never attaches a workspace) |

Response shape — a standard MCP tools/call result; the answer is the text content:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": { "content": [ { "type": "text", "text": "" } ] }
}

On a timeout the text is whatever agy produced before the kill followed by an [agy-mcp] TIMEOUT: ...; resume with 'agy -c' note, so partial work isn't lost. On other failures the text is an [agy-mcp] ERROR: ... string (agy missing, etc.) rather than a JSON-RPC error, so the agent always gets a readable reply.

---

Use cases & wiring it into your AI coding tools

The whole point: let one AI coding tool delegate work to Gemini via Antigravity, headlessly. Common setups:

| Use case | How | |---|---| | Claude Code asks Gemini for a second opinion / diff review | MCP server → agy_ask tool | | A CI step runs an agy prompt and captures the answer | agy-bridge "..." in the workflow | | A Python pipeline fans work out to agy | from agy_headless_bridge import run | | Codex / any MCP-capable agent delegates to agy | register the same MCP server | | Cron / scheduled job summarizes logs via agy | agy-bridge in the script |

Wire into Claude Code

Register the MCP server, then prompt Claude to use it:

claude mcp add --transport stdio antigravity -- \
    python -m agy_headless_bridge.mcp_server

> Windows: swap python for py -3.11 here too — see the note above and > [Troubleshooting](#troubleshooting--faq).

> Prompt to Claude Code: > "Use the agy_ask tool to ask Antigravity to review this function for edge > cases, then summarize its findings for me."

If you also want slash-command triggering and model selection, pair this bridge with the community antigravity-cc Claude Code plugin — that handles the /agy:* commands and Gemini/Claude model swap; this handles the headless I/O.

Wire into Codex (or any MCP client)

Add the server to the client's MCP config:

{
  "mcpServers": {
    "antigravity": {
      "command": "python",
      "args": ["-m", "agy_headless_bridge.mcp_server"]
    }
  }
}

> Prompt to the agent: > "Call agy_research with the query 'idiomatic error handling in Rust' and > turn the result into a checklist."

Use from a shell / CI script

ANSWER="$(agy-bridge 'Summarize the key risk in this diff in one sentence.')"
echo "$ANSWER"

---

Configuration

| Env var | Default | Meaning | |---|---|---| | AGY_PATH | auto-detect | Absolute path to the agy binary | | AGY_BRIDGE_TIMEOUT | 900 | Hard ceiling (absolute wall), in seconds | | AGY_BRIDGE_IDLE_TIMEOUT | 120 | Kill after this many seconds of no output from agy |

---

How clean() works

agy's pty output is a TUI stream, not plain text. clean() removes ANSI escapes (CSI/OSC — colors, cursor moves), \r repaints (a spinner overwrites one line; only the final paint is kept), and box-drawing / spinner glyphs (╭─╮ │ ⠋⠙⠹) — leaving just the model's answer.

What comes off the pty vs. what you get back:

RAW (off the pty)                          CLEANED (returned to you)
─────────────────────────────────────     ─────────────────────────
⠋ thinking…\r⠙ thinking…\r\x1b[2K          A closure is a function that
\x1b[32m╭─────────────╮\x1b[0m              captures variables from the
\x1b[32m│\x1b[0m A closure is a function     scope where it was defined.
that captures variables from the
scope where it was defined.
\x1b[32m╰─────────────╯\x1b[0m

---

Troubleshooting / FAQ

pip install fails on Windows building pywinpty — pywinpty is a native extension. If pip tries to build from source and errors with a compiler/cl.exe message, install the Microsoft C++ Build Tools (or use a Python where a prebuilt pywinpty wheel exists — recent CPython on Windows has them). Upgrade pip first: python -m pip install -U pip.

-32000 MCP connection error on Windows (interpreter mismatch) — bare python in the claude mcp add command can resolve to the wrong interpreter or the Windows Store stub, so the spawned server can't import the package and the connection fails. Use the [Python Launcher] instead — register the server with py -3.11 (matching the Python where you installed the package) in place of python. To confirm where the package actually landed, run pip show agy-headless-bridge and check the Location: field; if it points to a different Python than Claude Code spawns, that mismatch is the cause.

AgyNotFoundError — the bridge can't find agy. Set AGY_PATH to the absolute path of the binary, or make sure agy is on your PATH (agy --version should work in your shell).

Empty string returned — agy produced no output. Confirm it works in a real terminal first: agy -p "say hi". If that's also empty, the problem is agy/auth, not the bridge. Re-authenticate (agy interactively) or check ANTIGRAVITY_API_KEY.

AgyTimeoutError — agy hit a limit. Two triggers: the hard ceiling (AGY_BRIDGE_TIMEOUT, default 900s) and the idle timeout (AGY_BRIDGE_IDLE_TIMEOUT, default 120s — fires when agy emits nothing for that long). The error carries .partial (whatever agy produced first), and the CLI prints it before exiting. Widen the limits for long prompts: AGY_BRIDGE_TIMEOUT=1800 agy-bridge "...", --idle-timeout 300, or run(prompt, timeout=1800, idle_timeout=300). To continue a run that timed out, resume the agy session directly with agy -c.

Pseudo-terminal allocation fails — rare. On Windows it means pywinpty isn't importable (reinstall it). On POSIX it means the system is out of pty slots or pty.openpty() is denied (containers with no /dev/pts); run with a real pty available.

Garbled / partial output — open an issue with the OS, Python + agy version, and the raw output; clean() may need another glyph rule.

Development & CI

pip install -e ".[dev]"
pytest

Unit tests (cleaning, arg validation, binary discovery) always run. The live agy round-trip test auto-skips when agy isn't installed — so CI runners (which don't have agy) stay green and never need credentials. CI runs on Windows + Linux across Python 3.9 and 3.12.

---

Scope, non-goals & disclaimer

• Model selection (Gemini Pro / Flash / Claude inside agy) is not handled

here — it's an agy settings.json concern, covered by the antigravity-cc plugin. Pair the two.

• Does not install or authenticate agy, and ships no credentials.
• Automating any vendor CLI may interact with that vendor's terms / rate limits.

You are responsible for using agy within Google's terms of service. This project only changes how stdout is captured — it does not bypass auth, quotas, or any access control.

• Not affiliated with Google

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rhishi99
• Source: rhishi99/agy-headless-bridge
• License: MIT
• Homepage: https://rhishi99.github.io/agy-headless-bridge/

Install and usage instructions live in the source repository linked above.