# agy-headless-bridge [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/rhishi99/agy-headless-bridge  
**GitHub Stars:** 19  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agy-headless-bridge

## Description
Call the Google Antigravity CLI (agy) headlessly from any non-TTY context — Windows ConPTY + POSIX pty + MCP server. Fixes the empty-output bug (#76).

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/agy-headless-bridge/readme_