agy·headless·bridge

agy goes silent when nobody's at the terminal

agy -p "<prompt>" gates its stdout on isatty(). The moment stdout is not a real terminal — any automation — it prints nothing and exits 0. No error, no output, just emptiness.

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

$ python -m agy_headless_bridge "say hi"
Hi! How can I help?

flowchart TB
    subgraph BEF["❌ 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 AFT["✅ 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;
      

How a non-TTY caller gets clean output

The bridge spawns agy attached to a brand-new pseudo-terminal that requires no pre-existing parent tty — so it works from anywhere.

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

    classDef br fill:#1b1740,stroke:#7c5cff,color:#e7e9ef;
    classDef pty fill:#0c2730,stroke:#22d3ee,color:#e7e9ef;
    classDef agy fill:#0f2a1e,stroke:#34d399,color:#e7e9ef;
    class B,C,I br;
    class E,F,G pty;
    class H agy;
      

The tty handshake, step by step

sequenceDiagram
    autonumber
    participant C as Caller (non-TTY)
    participant B as bridge.run()
    participant P as fresh PTY
    participant A as agy -p

    C->>B: run("prompt")
    B->>B: find_agy() + pick allocator
    B->>P: allocate pseudo-terminal
    B->>A: spawn, stdout→PTY master
    A->>A: isatty(stdout)==True ✓
    A-->>P: streams answer + TUI chrome
    loop until EOF / timeout
        B->>P: read(4096)
    end
    B->>B: clean() — strip ANSI, collapse \r, drop glyphs
    B-->>C: clean text
      

One API, two pty backends

The API & the output pipeline

One core function, three entry points around it. Everything routes through run().

Core contract

run(prompt: str, timeout: float = 180, agy_path: str | None = None) -> str

What clean() strips

agy's pty output is a TUI stream, not plain text. clean() turns it back into the answer:

Raw off the pty vs. what you get back

⠋ thinking…\r⠙ thinking…\r\x1b[2K
\x1b[32m╭─────────────╮\x1b[0m
\x1b[32m│\x1b[0m A closure is a function
that captures variables from
the scope where it was defined.
\x1b[32m╰─────────────╯\x1b[0m

A closure is a function that
captures variables from the
scope where it was defined.

MCP response shape

{
  "jsonrpc": "2.0", "id": 2,
  "result": { "content": [ { "type": "text", "text": "<agy's cleaned answer>" } ] }
}

Both tools take one required string arg — agy_ask(prompt), agy_research(query). On failure the text is an [agy-mcp] ERROR: … string, not a JSON-RPC error, so the agent always gets a readable reply.

Troubleshooting

Three entry points

Prerequisites

This package only spawns the agy already on your machine — it ships no credentials and does not install or authenticate anything.

Wire it into your AI coding tools

Let one agent delegate work to Gemini via Antigravity, headlessly.

Wire into Claude Code

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

Want /agy:* slash commands + model selection too? Pair with the community antigravity-cc plugin — it handles triggering & model swap; this handles headless I/O.

Wire into Codex / any MCP client

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

From a shell / CI script

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

Install & use

You still need the Antigravity CLI itself installed and authenticated. The bridge locates it via $AGY_PATH → PATH → OS defaults.

Install

pip install agy-headless-bridge
# Windows pulls in pywinpty automatically; POSIX uses the stdlib pty module.

As a library

from agy_headless_bridge import run
print(run("Explain a closure in one line."))

As a CLI

python -m agy_headless_bridge "reply with exactly: OK"
# or the console script:
agy-bridge "reply with exactly: OK"

As an MCP server (Claude Code, etc.)

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

Exposes two tools — agy_ask and agy_research — so your agent can delegate work to Antigravity / Gemini.

Small, dependency-light, honest

Configuration

Scope & non-goals

Model selection (swapping Gemini Pro / Flash / Claude inside agy) is not handled here — that's an agy settings concern, already covered by the antigravity-cc Claude Code plugin (it patches settings.json). Pair the two. This bridge fixes the I/O layer they're missing; it does not install or authenticate agy.