Agy Headless Bridge

What agy-headless-bridge does

agy-headless-bridge addresses an Antigravity CLI behavior where agy -p can produce no stdout when its output is connected to a pipe or another non-terminal caller. The bridge gives each invocation a newly allocated pseudo-terminal, allowing agy to follow its terminal output path while the caller remains headless.

It is available in three forms:

• Python library: from agy_headless_bridge import run
• Command-line wrapper: agy-bridge "prompt"
• MCP server: python -m agy_headless_bridge.mcp_server

The package does not install or authenticate agy and does not include credentials. The Antigravity CLI must already be installed, authenticated, and usable in a normal terminal.

How it works

The bridge locates the agy executable using AGY_PATH, then the system PATH, followed by operating-system default locations. On Windows it uses pywinpty and ConPTY. On Linux and macOS it uses Python's standard pty support with os.openpty and subprocess.Popen.

Raw terminal output is passed through cleanup that removes ANSI control sequences, reduces carriage-return redraws, and drops spinner-related glyphs. The result is returned as plain text. The package also preserves partial output when a run stops and exposes typed errors for missing binaries, failed exits, quota exhaustion, and timeouts.

Setup and configuration

Install Python 3.9 or newer, the Antigravity CLI, and the package:

pip install agy-headless-bridge

Windows installs pywinpty as a dependency; POSIX platforms use the standard library pty implementation. To use the source tree, clone the repository and run pip install -e ..

Authenticate agy interactively or provide ANTIGRAVITY_API_KEY. Set AGY_PATH when the executable is not discoverable through the normal lookup order. The MCP server can be started with python -m agy_headless_bridge.mcp_server.

The repository also includes a Claude Code plugin. It runs a local stdio server from the plugin source using uv, so uv must be available on PATH. The plugin requires an installed and authenticated agy binary.

Tools and capabilities

The MCP interface provides two tools:

• agy_ask sends a prompt to agy. By default, the server adds its working directory as agy's workspace; use workspace: "none" to disable that behavior.
• agy_research sends research-oriented requests through agy.

agy_ask can be permitted to edit files or run commands only when the call uses skip_permissions: true and the server starts with AGY_BRIDGE_ALLOW_SKIP_PERMISSIONS=1. The Claude Code plugin does not enable that variable by default.

The Python library is a lower-level primitive and does not automatically add a workspace. The CLI and MCP layers provide their own workspace behavior.

Limitations and notes

The real agy round trip has been verified on Windows with ConPTY. POSIX pty mechanics are tested on Linux using a stub, while real agy behavior on bare-metal Linux and macOS remains less established.

The bridge depends on the agy installation and its authentication state. It does not bundle credentials, install agy, or open network ports. Calls ultimately use the agy process on the host, which communicates with Google's Antigravity service.

Local MCP servers load in Claude Code and local Cowork sessions; claude.ai chat does not load them. Newer agy releases may already emit output through pipes, but the bridge still supplies timeout handling, partial-output retention, typed failures, output cleanup, and the MCP interface.