companion-for-agy 1.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## [1.2.0-alpha.1] - 2026-06-07
+
+### Changed
+- Package renamed to `companion-for-agy` (legal/trademark distancing via "for" pattern)
+- Added "Unofficial" disclaimer to README and package description
+
+### Fixed
+- Short responses (≤2 chars like "4", "42", "ja") were incorrectly filtered as noise
+- Prompt-echo bug in `--no-tools` mode: the permission prefix ("IMPORTANT: Do not use...") was returned as the response instead of the actual answer
+- ConPTY space-loss in prompt echo: whitespace-normalized matching now handles "Donotuse" vs "Do not use"
+
+### Added
+- `stripPromptEcho()` — whitespace-tolerant prompt echo removal (word-by-word regex)
+- `extractResponse()` now accepts 4th parameter `effectiveFilter` for full prompt echo stripping
+- 5-phase state machine: Trust dialog auto-confirmation phase
+- Banner model detection: JSON reports actual model from agy's banner
+- 26 new tests (107 total): short answer extraction, prompt echo regression, stripPromptEcho unit tests
+- `companion-for-agy` CLI alias (alongside `agy-companion` for backward compatibility)
+
+## [1.1.0] - 2026-06-06
+
+### Changed
+- Cross-platform support: Windows, macOS, Linux (node-pty handles platform-specific PTY)
+- Auto-detection of agy binary via PATH, common install locations, env var fallback
+- node-pty loaded as standard npm dependency (no hardcoded path to gemini-cli internals)
+- Debug log writes to `./agy-debug.log` (CWD) instead of `~/.claude/scripts/`
+- CLI messages and usage text in English for international audience
+- Added English INIT_DONE_PATTERNS alongside German ones
+- Removed `"os": ["win32"]` restriction from package.json
+
+### Added
+- `findAgyPath()` exported function for programmatic agy detection
+- Test suite: 81 tests (unit, fixture, smoke) via `node:test`
+- `npm run deploy` and `npm run sync` scripts for local copy management
+- Comprehensive README with installation, troubleshooting, and usage docs
+
+## [1.0.0] - 2026-06-06
+
+### Hinzugefügt
+- ConPTY-basierter Wrapper für agy (Antigravity CLI)
+- ANSI-Color-basierte Response-Extraktion (RGB 232,234,237)
+- Fallback: Zeilen-basierte Noise-Filterung
+- 4-Phasen State-Machine (Startup → Init → Question → Response)
+- Adaptives Timing (10s während Generierung, 2.5s nach Abschluss)
+- Permission-System mit 5 Modi: sandbox, skip-permissions, no-tools, researcher, read-only
+- Custom allow/deny Regeln (kompatibel mit agys settings.json-Format)
+- JSON-Output-Modus (--json)
+- Konfigurierbare Pfade via Umgebungsvariablen
+- Prompt-Sanitisierung gegen PTY-Injection
+- Graceful Shutdown (Ctrl+C → Grace-Period → kill)
+- Debug-Modus mit PTY-Output-Log

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Geiger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# companion-for-agy
+
+<p align="center">
+  <img src="assets/logo.png" alt="companion-for-agy Logo" width="200" height="200" />
+</p>
+
+[![Deutsch](https://img.shields.io/badge/lang-Deutsch-blue)](README_de.md)
+
+> **Unofficial** — not affiliated with or endorsed by Google.
+
+PTY-based wrapper for **agy** (Antigravity CLI / Gemini CLI) that captures Gemini responses from subprocesses.
+
+## Problem
+
+`agy -p` (print mode) returns exit 0 but writes no output to stdout — the TUI text-drip renderer (`text_drip.go`) writes to the terminal buffer instead. This is a known bug:
+
+- [antigravity-cli#76](https://github.com/google-antigravity/antigravity-cli/issues/76)
+- [gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)
+- [antigravity-cli#115](https://github.com/google-antigravity/antigravity-cli/issues/115)
+
+This means no other agent (Claude Code, Codex, CI/CD) can programmatically read agy's responses.
+
+## Solution
+
+`companion-for-agy` spawns agy inside a virtual terminal via `node-pty` (ConPTY on Windows, forkpty on macOS/Linux) and extracts the response from the ANSI color stream. agy's response text uses `RGB(232,234,237)` — the wrapper tracks ANSI color state and collects only text in that color.
+
+> **Platform note:** The ANSI color extraction (`RGB(232,234,237)`) and the `--model` flag have been verified on **Windows** with agy >= 1.1. macOS and Linux are expected to work via `node-pty` since agy uses the same Go TUI renderer. However:
+> - **agy v1.0.x** (Homebrew `antigravity-cli`) does not support `--model` — the tool will fail with "flags provided but not defined". Update agy or omit `--model` (requires code change).
+> - The exact RGB response color has not been independently confirmed on non-Windows platforms. If color extraction returns empty results, try `--debug` and check `agy-debug.log` for the actual color codes.
+
+## Installation
+
+```bash
+npm install -g companion-for-agy
+```
+
+### Prerequisites
+
+- **Node.js >= 18**
+- **agy** ([Gemini CLI](https://github.com/google-gemini/gemini-cli)) installed and authenticated
+- **C/C++ build tools** for `node-pty` native compilation:
+  - **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + Python 3
+  - **macOS:** `xcode-select --install`
+  - **Linux:** `sudo apt install build-essential python3` (Debian/Ubuntu)
+
+### Troubleshooting `node-pty` build errors
+
+If `npm install` fails with native compilation errors:
+
+```bash
+# All platforms: rebuild native modules
+npm rebuild node-pty
+
+# Windows: if cl.exe is not found, install Visual Studio Build Tools
+# then open "Developer Command Prompt" or run from "x64 Native Tools"
+```
+
+## Usage
+
+```bash
+companion-for-agy [options] "prompt"
+```
+
+### Permission Modes
+
+| Flag | Description |
+|------|-------------|
+| `--sandbox` | Sandbox mode (default) — tools in container |
+| `--skip-permissions` | All tools without confirmation (YOLO) |
+| `--no-tools` | Pure chat — no tool execution |
+| `--researcher` | Web search allowed, no file changes |
+| `--read-only` | Read-only, no modifications |
+
+### Custom Rules
+
+```bash
+--allow "read_file(/path)"    # Allowlist rule (repeatable)
+--deny "command(rm)"           # Denylist rule (repeatable)
+```
+
+Formats match agy's own permission system (`settings.json`).
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--model <model>` | Gemini model (default: `gemini-3.5-flash`) |
+| `--timeout <ms>` | Timeout in ms (default: 120000) |
+| `--json` | Output as JSON object |
+| `--debug` | Save raw PTY output to `agy-debug.log` |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGY_COMPANION_AGY_PATH` | Path to agy binary (auto-detected if not set) |
+| `AGY_PATH` | Alternative path to agy binary |
+
+### Examples
+
+```bash
+# Simple question
+companion-for-agy "What is the capital of Bavaria?"
+
+# As advisor (no tool use)
+companion-for-agy --no-tools "Review this code: ..."
+
+# Web research
+companion-for-agy --researcher "Latest info on Node.js 24"
+
+# Read-only with additional git permission
+companion-for-agy --read-only --allow "command(git log)" "prompt"
+
+# JSON output for programmatic use
+companion-for-agy --json --model gemini-3.5-pro "prompt"
+# → {"response":"...","model":"Gemini 3.5 Pro (High)","requestedModel":"gemini-3.5-pro","permissionMode":"sandbox"}
+```
+
+> **JSON fields:** `model` reports the actual model detected from agy's banner (e.g., `"Gemini 3.5 Flash (Medium)"`). `requestedModel` is what was passed via `--model`. If banner detection fails, `model` falls back to `requestedModel`.
+
+## How It Works
+
+```
+┌────────────────────┐       PTY       ┌─────────────┐
+│ companion-for-agy  │ ─────────────▸  │     agy     │
+│     (Node.js)      │ ◂────────────── │  (Go TUI)   │
+│                    │  ANSI stream    │             │
+│  Color-Based       │                 │ text_drip.go│
+│  Extraction        │                 │ RGB(232,234,│
+│                    │                 │     237)    │
+└────────┬───────────┘                 └─────────────┘
+         │
+         ▼ stdout
+     Response text
+```
+
+**5-Phase State Machine:**
+
+1. **Trust** — detect and auto-confirm workspace trust dialog
+2. **Startup** — detect main UI readiness (`? for shortcuts`)
+3. **Init** — wait for GEMINI.md initialization (pattern matching or 20s fallback)
+4. **Question** — send prompt, set response marker
+5. **Response** — read response via ANSI color extraction, adaptive idle timer
+
+## Use Cases
+
+- **Multi-agent orchestration**: Claude Code, Codex, or other agents querying Gemini via agy
+- **CI/CD pipelines**: automated Gemini queries in build scripts
+- **Scripting**: any scenario where agy's response needs to be captured as text
+
+## Background
+
+This tool was built because three CLI agents — **Claude Code**, **Codex**, and **agy** — need to call each other as fallback advisors. While Claude → Codex and agy → Claude/Codex already work, Claude → agy was blocked by the TUI stdout bug.
+
+## License
+
+MIT

package/README_de.md

@@ -0,0 +1,126 @@
+# companion-for-agy
+
+<p align="center">
+  <img src="assets/logo.png" alt="companion-for-agy Logo" width="200" height="200" />
+</p>
+
+[![English](https://img.shields.io/badge/lang-English-blue)](README.md)
+
+> **Inoffiziell** — nicht verbunden mit oder empfohlen von Google.
+
+PTY-basierter Wrapper für **agy** (Antigravity CLI / Gemini CLI), der Gemini-Antworten aus Subprozessen erfasst.
+
+## Problem
+
+`agy -p` (Print-Modus) gibt Exit 0 zurück, schreibt aber keinen Output nach stdout — der TUI Text-Drip-Renderer (`text_drip.go`) schreibt in den Terminal-Buffer. Das ist ein bekannter Bug:
+
+- [antigravity-cli#76](https://github.com/google-antigravity/antigravity-cli/issues/76)
+- [gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)
+- [antigravity-cli#115](https://github.com/google-antigravity/antigravity-cli/issues/115)
+
+Kein anderer Agent (Claude Code, Codex, CI/CD) kann dadurch agys Antworten programmatisch lesen.
+
+## Lösung
+
+`companion-for-agy` startet agy in einem virtuellen Terminal via `node-pty` (ConPTY unter Windows, forkpty unter macOS/Linux) und extrahiert die Antwort aus dem ANSI-Farbstream. agys Antworttext nutzt `RGB(232,234,237)` — der Wrapper verfolgt den ANSI-Farbstatus und sammelt nur Text in dieser Farbe.
+
+> **Plattformhinweis:** Die ANSI-Farbextraktion (`RGB(232,234,237)`) wurde unter **Windows** (ConPTY) verifiziert. macOS und Linux sollten über `node-pty` funktionieren, da agy denselben Go-TUI-Renderer verwendet, aber die exakten RGB-Werte wurden auf diesen Plattformen noch nicht unabhängig bestätigt. Falls die Farbextraktion leere Ergebnisse liefert, `--debug` verwenden und `agy-debug.log` auf die tatsächlichen Farbcodes prüfen.
+
+## Installation
+
+```bash
+npm install -g companion-for-agy
+```
+
+### Voraussetzungen
+
+- **Node.js >= 18**
+- **agy** ([Gemini CLI](https://github.com/google-gemini/gemini-cli)) installiert und authentifiziert
+- **C/C++ Build-Tools** für `node-pty` Native-Kompilierung:
+  - **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + Python 3
+  - **macOS:** `xcode-select --install`
+  - **Linux:** `sudo apt install build-essential python3` (Debian/Ubuntu)
+
+## Verwendung
+
+```bash
+companion-for-agy [optionen] "prompt"
+```
+
+### Berechtigungsmodi
+
+| Flag | Beschreibung |
+|------|-------------|
+| `--sandbox` | Sandbox-Modus (Standard) — Tools im Container |
+| `--skip-permissions` | Alle Tools ohne Bestätigung (YOLO) |
+| `--no-tools` | Reiner Chat — keine Tool-Ausführung |
+| `--researcher` | Web-Suche erlaubt, keine Dateiänderungen |
+| `--read-only` | Nur Lesen, keine Änderungen |
+
+### Eigene Regeln
+
+```bash
+--allow "read_file(/pfad)"    # Erlaubnisregel (wiederholbar)
+--deny "command(rm)"           # Verbots-Regel (wiederholbar)
+```
+
+### Optionen
+
+| Flag | Beschreibung |
+|------|-------------|
+| `--model <modell>` | Gemini-Modell (Standard: `gemini-3.5-flash`) |
+| `--timeout <ms>` | Timeout in ms (Standard: 120000) |
+| `--json` | Ausgabe als JSON-Objekt |
+| `--debug` | Rohen PTY-Output in `agy-debug.log` speichern |
+
+### Beispiele
+
+```bash
+# Einfache Frage
+companion-for-agy "Was ist die Hauptstadt von Bayern?"
+
+# Als Berater (keine Tool-Nutzung)
+companion-for-agy --no-tools "Überprüfe diesen Code: ..."
+
+# Web-Recherche
+companion-for-agy --researcher "Neueste Infos zu Node.js 24"
+
+# JSON-Output für programmatische Nutzung
+companion-for-agy --json --model gemini-3.5-pro "prompt"
+```
+
+> **JSON-Felder:** `model` meldet das tatsächliche Modell aus agys Banner (z.B. `"Gemini 3.5 Flash (Medium)"`). `requestedModel` ist was via `--model` übergeben wurde.
+
+## Funktionsweise
+
+```
+┌────────────────────┐       PTY       ┌─────────────┐
+│ companion-for-agy  │ ─────────────▸  │     agy     │
+│     (Node.js)      │ ◂────────────── │  (Go TUI)   │
+│                    │  ANSI-Stream    │             │
+│  Farbbasierte      │                 │ text_drip.go│
+│  Extraktion        │                 │ RGB(232,234,│
+│                    │                 │     237)    │
+└────────┬───────────┘                 └─────────────┘
+         │
+         ▼ stdout
+     Antworttext
+```
+
+**5-Phasen State Machine:**
+
+1. **Trust** — Workspace-Trust-Dialog erkennen und automatisch bestätigen
+2. **Startup** — Haupt-UI-Bereitschaft erkennen (`? for shortcuts`)
+3. **Init** — GEMINI.md-Initialisierung abwarten (Pattern-Matching oder 20s Fallback)
+4. **Question** — Prompt senden, Response-Marker setzen
+5. **Response** — Antwort via ANSI-Farbextraktion lesen, adaptiver Idle-Timer
+
+## Anwendungsfälle
+
+- **Multi-Agent-Orchestrierung:** Claude Code, Codex oder andere Agenten fragen Gemini via agy
+- **CI/CD-Pipelines:** Automatisierte Gemini-Abfragen in Build-Scripts
+- **Scripting:** Jedes Szenario wo agys Antwort als Text benötigt wird
+
+## Lizenz
+
+MIT

package/ROADMAP.md

@@ -0,0 +1,53 @@
+# Roadmap
+
+## Platform Status
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| **Windows** | Verified | ConPTY, agy >= 1.1, RGB(232,234,237) confirmed |
+| **macOS** | Untested | node-pty (forkpty) expected to work, color values unconfirmed |
+| **Linux** | Untested | node-pty (forkpty) expected to work, color values unconfirmed |
+
+## Planned
+
+### macOS / Linux Support
+
+The tool is currently **Windows-only verified**. macOS and Linux are expected to work via `node-pty` (which uses forkpty instead of ConPTY), but the following items need verification:
+
+**TODOs:**
+- [ ] Verify ANSI response color on macOS (is it still `RGB(232,234,237)` or does agy use a different palette?)
+- [ ] Verify ANSI response color on Linux
+- [ ] Handle agy v1.0.x (Homebrew `antigravity-cli`) which lacks `--model` flag — make `--model` conditional or skip it when agy version < 1.1
+- [ ] Test node-pty spawn-helper permissions after `npm install` on macOS (prebuilt binaries need +x)
+- [ ] Test trust dialog auto-confirmation flow on macOS/Linux
+- [ ] Add platform-specific CI smoke tests (requires agy authentication in CI — may need to remain manual)
+
+**Diagnostics available now:**
+- `--debug` flag saves raw PTY output to `agy-debug.log` — inspect for actual ANSI color codes on any platform
+- `AGY_COMPANION_RESPONSE_RGB` environment variable override (planned, not yet implemented)
+
+### Color Fallback / Auto-Probe
+The current ANSI color extraction relies on `RGB(232,234,237)` as the response color. This has been verified on Windows (ConPTY). If agy changes its color scheme or uses different values on macOS/Linux, extraction silently fails.
+
+**Ideas:**
+- `--probe-color`: Run a known-answer prompt ("What is 2+2?"), scan the raw ANSI stream for the color that wraps "4", and cache it per platform
+- Platform-specific RGB override via environment variable (`AGY_COMPANION_RESPONSE_RGB`)
+- Heuristic: find the most frequent non-UI color in the stream
+
+### Multi-Turn Mode
+Currently, each invocation spawns a fresh agy process (one question, one answer). A persistent mode that keeps the PTY alive across multiple prompts would reduce startup overhead for batch workloads.
+
+### Streaming Output
+Emit response tokens as they arrive (line-by-line or chunk-by-chunk) instead of buffering until completion. Useful for long responses where the caller wants progressive output.
+
+### Response Format Detection
+Detect whether agy's response is Markdown, JSON, or plain text and expose this in the JSON output (`"format": "markdown"`).
+
+## Completed (v1.2.0-alpha.1)
+
+- Trust dialog auto-confirmation (5-phase state machine)
+- Banner model detection (actual model from agy's banner)
+- Short response noise filter fix (answers like "4" or "42")
+- Prompt-echo stripping in no-tools mode (ConPTY space-loss tolerant)
+- Cross-platform agy binary auto-detection
+- node-pty as standard npm dependency

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "companion-for-agy",
+  "version": "1.2.0-alpha.1",
+  "description": "Unofficial PTY-based wrapper for agy (Antigravity CLI / Gemini CLI) — captures Gemini responses that agy writes to the terminal buffer instead of stdout",
+  "type": "module",
+  "main": "src/agy-companion.mjs",
+  "bin": {
+    "companion-for-agy": "src/agy-companion.mjs",
+    "agy-companion": "src/agy-companion.mjs"
+  },
+  "files": [
+    "src/agy-companion.mjs",
+    "README.md",
+    "README_de.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/agy-companion.mjs",
+    "test": "node --test _tests/unit.test.mjs _tests/fixture.test.mjs",
+    "test:unit": "node --test _tests/unit.test.mjs",
+    "test:fixture": "node --test _tests/fixture.test.mjs",
+    "test:smoke": "node --test _tests/smoke.test.mjs",
+    "test:all": "node --test _tests/unit.test.mjs _tests/fixture.test.mjs _tests/smoke.test.mjs",
+    "deploy": "node -e \"require('fs').copyFileSync('src/agy-companion.mjs', require('path').join(require('os').homedir(), '.claude', 'scripts', 'agy-companion.mjs'));console.log('Deployed to ~/.claude/scripts/agy-companion.mjs')\"",
+    "sync": "git pull && npm run deploy"
+  },
+  "keywords": [
+    "agy",
+    "antigravity",
+    "gemini",
+    "gemini-cli",
+    "cli",
+    "wrapper",
+    "pty",
+    "conpty",
+    "claude-code",
+    "multi-agent",
+    "llm"
+  ],
+  "author": "Lukas Geiger",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dev-bricks/companion-for-agy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dev-bricks/companion-for-agy/issues"
+  },
+  "homepage": "https://github.com/dev-bricks/companion-for-agy#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "node-pty": "^1.0.0"
+  }
+}

package/src/agy-companion.mjs

@@ -0,0 +1,670 @@
+#!/usr/bin/env node
+/**
+ * companion-for-agy — Unofficial PTY-based wrapper for agy (Antigravity CLI / Gemini CLI)
+ *
+ * Problem: agy's TUI text-drip renderer writes to the terminal buffer, not stdout.
+ *          From subprocesses (Claude Code, Codex, CI/CD), no output is capturable.
+ *          Additionally, GEMINI.md triggers a "first action" that consumes the
+ *          single -p turn for session initialization.
+ *
+ * Solution: 1. node-pty creates a virtual terminal (ConPTY on Windows, forkpty on Unix)
+ *           2. Interactive mode: wait for init, THEN send the actual question
+ *           3. Extract response via ANSI color ([38;2;232;234;237m = response color)
+ *           4. Fallback: line-based noise filtering
+ *
+ * Usage:
+ *   agy-companion [options] "prompt"
+ *   node src/agy-companion.mjs [options] "prompt"
+ */
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, execSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import process from 'node:process';
+
+// ---------- Defaults ----------
+
+export const DEFAULT_MODEL = 'gemini-3.5-flash';
+export const DEFAULT_TIMEOUT_MS = 120000;
+export const RESPONSE_IDLE_MS = 10000;
+export const RESPONSE_DONE_IDLE_MS = 2500;
+
+const require = createRequire(import.meta.url);
+
+// ---------- Auto-Detection ----------
+
+export function findAgyPath() {
+  if (process.env.AGY_COMPANION_AGY_PATH) return process.env.AGY_COMPANION_AGY_PATH;
+  if (process.env.AGY_PATH) return process.env.AGY_PATH;
+
+  const agyName = process.platform === 'win32' ? 'agy.exe' : 'agy';
+
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    const result = execFileSync(cmd, [agyName], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const firstLine = result.split(/\r?\n/)[0].trim();
+    if (firstLine && fs.existsSync(firstLine)) return firstLine;
+  } catch (_) {}
+
+  if (process.platform === 'win32') {
+    const localApp = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    const candidate = path.join(localApp, 'agy', 'bin', 'agy.exe');
+    if (fs.existsSync(candidate)) return candidate;
+  } else {
+    for (const p of [
+      path.join(os.homedir(), '.local', 'bin', 'agy'),
+      '/usr/local/bin/agy',
+      '/opt/homebrew/bin/agy',
+    ]) {
+      if (fs.existsSync(p)) return p;
+    }
+  }
+
+  return null;
+}
+
+export const AGY_PATH = findAgyPath();
+
+// ---------- Permission-Presets ----------
+
+export const PERMISSION_PRESETS = {
+  sandbox: {
+    agyFlags: ['--sandbox'],
+    allow: [],
+    deny: [],
+  },
+  'skip-permissions': {
+    agyFlags: ['--dangerously-skip-permissions'],
+    allow: [],
+    deny: [],
+  },
+  'no-tools': {
+    agyFlags: ['--sandbox'],
+    allow: [],
+    deny: ['command(*)', 'write_file(*)', 'edit_file(*)', 'read_file(*)'],
+    promptPrefix: 'IMPORTANT: Do not use any tools. Answer based on your knowledge only.\n\n',
+  },
+  researcher: {
+    agyFlags: ['--sandbox'],
+    allow: ['google_search(*)', 'web_search(*)', 'web_fetch(*)', 'read_file(*)'],
+    deny: ['write_file(*)', 'edit_file(*)', 'command(rm *)', 'command(del *)'],
+  },
+  'read-only': {
+    agyFlags: ['--sandbox'],
+    allow: ['read_file(*)'],
+    deny: ['write_file(*)', 'edit_file(*)', 'command(rm *)', 'command(del *)'],
+  },
+};
+
+// ---------- State-Machine-Patterns ----------
+
+export const TRUST_DIALOG_PATTERN = /Do you trust/;
+export const BANNER_MODEL_PATTERN = /Gemini \d[\d.]* \w+(?:\s*\([^)]*\))?/;
+
+export const STARTUP_DONE_PATTERNS = [
+  /\? for shortcuts/,
+];
+
+export const INIT_DONE_PATTERNS = [
+  /Zusammenfassung der Arbeit/,
+  /Ich (bin|verwende|laufe) (derzeit |gerade )?(das Modell|auf dem Modell)/i,
+  /Das aktive Modell/i,
+  /Modell wurde als/i,
+  /aktive Modell/i,
+  /active model/i,
+  /using model/i,
+  /session (initialized|started|ready)/i,
+];
+
+export const INIT_FALLBACK_MS = 20000;
+
+// ---------- Prompt-Sanitisierung ----------
+
+export function sanitizeForPty(text) {
+  return text
+    .replace(/[\x00-\x08\x0b\x0e-\x1f]/g, '')
+    .replace(/\x03/g, '')
+    .replace(/\r\n|\r|\n/g, ' ');
+}
+
+// ---------- ANSI/VT100 Bereinigung ----------
+
+export function stripAnsi(raw) {
+  return raw
+    .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b[()][AB012]/g, '')
+    .replace(/\x1b[=><NOMlmiHI78DEHMNO]/g, '')
+    .replace(/\x1b./g, '')
+    .replace(/[\x00-\x08\x0b\x0e-\x1f\x7f]/g, '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n');
+}
+
+export function isNoiseLine(line, promptFilter = '') {
+  const t = line.trim();
+  if (!t) return true;
+  if (/^[│┌└┐┘├┤┬┴┼─═╔╗╚╝╠╣╦╩╬▸►◉●▲▼◆□■╭╮╯╰]+$/.test(t)) return true;
+  if (t.startsWith('>')) return true;
+  if (/[⣾⣷⣯⣟⡿⢿⣻⣽⠿⠾⠽⠼⠻⠺⠹⠸⠷⠶⠵⠴⠳⠲⠱⠰]/.test(t)) return true;
+  if (/Generating|esc to cancel|for shortcuts|tokens/i.test(t)) return true;
+  if (t === '?' || t === '? for shortcuts') return true;
+  if (/^Gemini \d/.test(t)) return true;
+  if (/^\d+\s*tokens$/.test(t)) return true;
+  if (/^▸\s/.test(t)) return true;
+  if (/^(Checking|Reading|Writing|Searching|Fetching|Analyzing|Executing)\b/i.test(t)) return true;
+  if (t.includes('@googlemail.com') || t.includes('@gmail.com')) return true;
+  if (promptFilter && t.includes(promptFilter.slice(0, 20))) return true;
+  return false;
+}
+
+// ---------- Response-Extraktion via ANSI-Farbe ----------
+
+export function extractByResponseColor(rawSection) {
+  const segments = [];
+  let inResponseColor = false;
+  let pos = 0;
+  const src = rawSection;
+
+  while (pos < src.length) {
+    if (src[pos] === '\x1b') {
+      if (src[pos + 1] === '[') {
+        let end = pos + 2;
+        while (end < src.length && !/[A-Za-z]/.test(src[end])) end++;
+        const cmd = src[end];
+        const params = src.slice(pos + 2, end);
+        if (params === '38;2;232;234;237' && cmd === 'm') {
+          inResponseColor = true;
+        } else if (cmd === 'm') {
+          inResponseColor = false;
+        }
+        pos = end + 1;
+      } else if (src[pos + 1] === ']') {
+        let end = pos + 2;
+        while (end < src.length && src[end] !== '\x07' &&
+               !(src[end] === '\x1b' && src[end + 1] === '\\')) end++;
+        pos = src[end] === '\x07' ? end + 1 : end + 2;
+      } else {
+        pos += 2;
+      }
+    } else if (inResponseColor) {
+      let textEnd = pos;
+      while (textEnd < src.length && src[textEnd] !== '\x1b') textEnd++;
+      const rawText = src.slice(pos, textEnd);
+      const text = rawText.replace(/[\x00-\x08\x0b\x0e-\x1f\x7f]/g, '');
+      if (text.length > 0) segments.push(text);
+      pos = textEnd;
+    } else {
+      pos++;
+    }
+  }
+
+  if (segments.length === 0) return null;
+
+  const deduped = segments.filter((s, i) =>
+    !segments.some((o, j) => j !== i && o.length > s.length && o.startsWith(s))
+  );
+
+  const combined = deduped.join('').trim();
+  return combined.length > 0 ? combined : null;
+}
+
+export function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function stripPromptEcho(text, filter) {
+  if (!filter || !text) return null;
+  const normText = text.replace(/\s+/g, '');
+  const normFilter = filter.replace(/\s+/g, '');
+  const matchLen = Math.min(30, normFilter.length);
+  if (matchLen < 5 || !normText.includes(normFilter.slice(0, matchLen))) return null;
+  const words = filter.split(/\s+/).filter(w => w.length > 0);
+  const regexStr = words.map(w => escapeRegex(w)).join('\\s*');
+  const clean = text.replace(new RegExp(regexStr), '').trim();
+  return clean.length > 0 ? clean : '';
+}
+
+export function extractResponse(stripped, rawSection, promptFilter = '', effectiveFilter = '') {
+  if (rawSection) {
+    const colorResult = extractByResponseColor(rawSection);
+    if (colorResult && colorResult.length > 0) {
+      const echoFilter = effectiveFilter || promptFilter;
+      if (echoFilter) {
+        const cleaned = stripPromptEcho(colorResult, echoFilter);
+        if (cleaned !== null) return cleaned || null;
+      }
+      if (promptFilter && promptFilter !== echoFilter) {
+        const cleaned = stripPromptEcho(colorResult, promptFilter);
+        if (cleaned !== null) return cleaned || null;
+      }
+      return colorResult;
+    }
+  }
+
+  const lines = stripped.split('\n');
+  const meaningful = lines.filter(l => !isNoiseLine(l, promptFilter));
+  if (meaningful.length === 0) return null;
+
+  let best = meaningful.join('\n').trim();
+  if (promptFilter) {
+    const promptWords = promptFilter.split(/\s+/).slice(0, 5).join('');
+    best = best.split('\n')
+      .filter(l => !l.replace(/\s/g, '').startsWith(promptWords.replace(/\s/g, '')))
+      .join('\n')
+      .trim();
+  }
+  return best || null;
+}
+
+// ---------- CLI Main ----------
+
+const __filename = fileURLToPath(import.meta.url);
+
+function isMainModule() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(path.resolve(__filename));
+  } catch (_) {
+    return path.resolve(process.argv[1] || '') === path.resolve(__filename);
+  }
+}
+
+if (isMainModule()) {
+
+  function printUsage() {
+    process.stderr.write([
+      'companion-for-agy — Unofficial PTY wrapper for agy (Antigravity CLI / Gemini CLI)',
+      '',
+      'Usage: companion-for-agy [options] "prompt"',
+      '',
+      'Permission modes (mutually exclusive):',
+      '  --sandbox              Sandbox mode (default) — tools in container',
+      '  --skip-permissions     All tools without confirmation (YOLO)',
+      '  --no-tools             Pure chat — no tool execution',
+      '  --researcher           Web search allowed, no file changes',
+      '  --read-only            Read-only, no modifications',
+      '',
+      'Custom rules (combinable with modes):',
+      '  --allow <pattern>      Allowlist rule (repeatable)',
+      '  --deny <pattern>       Denylist rule (repeatable)',
+      '  Formats: read_file(/path), command(git), write_file(*)',
+      '',
+      'Options:',
+      '  --model <model>        Gemini model (default: gemini-3.5-flash)',
+      '  --timeout <ms>         Timeout in ms (default: 120000)',
+      '  --json                 Output as JSON object',
+      '  --debug                Save raw PTY output to agy-debug.log',
+      '  --help                 Show this help',
+      '',
+      'Models:',
+      '  gemini-1.5-flash   gemini-1.5-pro',
+      '  gemini-2.0-flash   gemini-2.0-pro',
+      '  gemini-3.5-flash   gemini-3.5-pro',
+      '',
+      'Environment variables:',
+      '  AGY_COMPANION_AGY_PATH   Path to agy binary',
+      '  AGY_PATH                 Alternative path to agy binary',
+      '',
+      'Examples:',
+      '  companion-for-agy "What is the capital of Bavaria?"',
+      '  companion-for-agy --no-tools "Review this code: ..."',
+      '  companion-for-agy --researcher "Latest info on Node.js 24"',
+      '  companion-for-agy --read-only --allow "command(git log)" "prompt"',
+      '  companion-for-agy --json --model gemini-3.5-pro "prompt"',
+    ].join('\n') + '\n');
+  }
+
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  let model = DEFAULT_MODEL;
+  let timeoutMs = DEFAULT_TIMEOUT_MS;
+  let debug = false;
+  let jsonOutput = false;
+  let permissionMode = 'sandbox';
+  const customAllow = [];
+  const customDeny = [];
+  let userPromptForFilter = '';
+  let effectivePromptForFilter = '';
+  const promptParts = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if ((arg === '--model' || arg === '-m') && rawArgs[i + 1]) {
+      model = rawArgs[++i];
+    } else if (arg === '--timeout' && rawArgs[i + 1]) {
+      const t = parseInt(rawArgs[++i], 10);
+      if (!isNaN(t) && t > 0) timeoutMs = t;
+    } else if (arg === '--debug') {
+      debug = true;
+    } else if (arg === '--json') {
+      jsonOutput = true;
+    } else if (arg === '--sandbox') {
+      permissionMode = 'sandbox';
+    } else if (arg === '--skip-permissions') {
+      permissionMode = 'skip-permissions';
+    } else if (arg === '--no-tools') {
+      permissionMode = 'no-tools';
+    } else if (arg === '--researcher') {
+      permissionMode = 'researcher';
+    } else if (arg === '--read-only') {
+      permissionMode = 'read-only';
+    } else if (arg === '--allow' && rawArgs[i + 1]) {
+      customAllow.push(rawArgs[++i]);
+    } else if (arg === '--deny' && rawArgs[i + 1]) {
+      customDeny.push(rawArgs[++i]);
+    } else if (!arg.startsWith('-')) {
+      promptParts.push(arg);
+    }
+  }
+
+  const userPrompt = promptParts.join(' ').trim();
+  if (!userPrompt) {
+    process.stderr.write('Error: No prompt provided.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+  userPromptForFilter = userPrompt;
+
+  // ---------- Permission-Setup ----------
+
+  const preset = PERMISSION_PRESETS[permissionMode];
+  const allAllow = [...preset.allow, ...customAllow];
+  const allDeny = [...preset.deny, ...customDeny];
+
+  const tempWorkspace = path.join(os.tmpdir(), `agy-companion-${process.pid}`);
+  let tempSettingsCreated = false;
+
+  if (allAllow.length > 0 || allDeny.length > 0) {
+    const geminiDir = path.join(tempWorkspace, '.gemini');
+    fs.mkdirSync(geminiDir, { recursive: true });
+    const settings = { permissions: {} };
+    if (allAllow.length > 0) settings.permissions.allow = allAllow;
+    if (allDeny.length > 0) settings.permissions.deny = allDeny;
+    fs.writeFileSync(path.join(geminiDir, 'settings.json'), JSON.stringify(settings, null, 2));
+    tempSettingsCreated = true;
+  } else {
+    fs.mkdirSync(tempWorkspace, { recursive: true });
+  }
+
+  const promptPrefix = preset.promptPrefix || '';
+  const effectivePrompt = promptPrefix + userPrompt;
+  effectivePromptForFilter = effectivePrompt;
+
+  // ---------- node-pty ----------
+
+  let pty;
+  const nodePtyOverride = process.env.AGY_COMPANION_PTY_PATH;
+
+  if (nodePtyOverride) {
+    try {
+      pty = require(nodePtyOverride);
+    } catch (err) {
+      process.stderr.write(`[agy-companion] Failed to load node-pty from ${nodePtyOverride}:\n  ${err.message}\n`);
+      process.exit(1);
+    }
+  } else {
+    try {
+      pty = require('node-pty');
+    } catch (_) {
+      let loaded = false;
+      const geminiPtySuffix = path.join('@google', 'gemini-cli', 'node_modules', 'node-pty');
+      const candidates = [];
+
+      if (process.platform === 'win32' && process.env.APPDATA) {
+        candidates.push(path.join(process.env.APPDATA, 'npm', 'node_modules', geminiPtySuffix));
+      }
+      try {
+        const globalRoot = execSync('npm root -g', {
+          encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        candidates.push(path.join(globalRoot, geminiPtySuffix));
+      } catch (_) { /* npm not available */ }
+
+      for (const candidate of candidates) {
+        try {
+          pty = require(candidate);
+          loaded = true;
+          break;
+        } catch (_) { /* try next */ }
+      }
+
+      if (!loaded) {
+        process.stderr.write(
+          `[agy-companion] Failed to load node-pty.\n` +
+          `[agy-companion] Install via: npm install -g companion-for-agy\n` +
+          `[agy-companion] Or set AGY_COMPANION_PTY_PATH environment variable.\n`
+        );
+        process.exit(1);
+      }
+    }
+  }
+
+  // ---------- Resolve agy path ----------
+
+  const resolvedAgyPath = AGY_PATH;
+  if (!resolvedAgyPath) {
+    process.stderr.write(
+      `[agy-companion] agy not found.\n` +
+      `[agy-companion] Install agy: https://github.com/google-gemini/gemini-cli\n` +
+      `[agy-companion] Or set AGY_PATH / AGY_COMPANION_AGY_PATH environment variable.\n`
+    );
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(resolvedAgyPath)) {
+    process.stderr.write(`[agy-companion] agy not found at: ${resolvedAgyPath}\n`);
+    process.exit(1);
+  }
+
+  // ---------- Start agy ----------
+
+  const agyArgs = ['--model', model, ...preset.agyFlags];
+
+  process.stderr.write(
+    `[agy-companion] Starting agy ${agyArgs.join(' ')} (${permissionMode})...\n`
+  );
+
+  const ptyProc = pty.spawn(resolvedAgyPath, agyArgs, {
+    name: 'xterm-256color',
+    cols: 220,
+    rows: 50,
+    cwd: tempWorkspace,
+    env: { ...process.env, TERM: 'xterm-256color' },
+  });
+
+  let rawBuffer = '';
+  let detectedModel = null;
+  let trustHandled = false;
+  let startupComplete = false;
+  let initDone = false;
+  let questionSent = false;
+  let responseStartMark = 0;
+  let initIdleTimer = null;
+  let responseIdleTimer = null;
+  let finished = false;
+
+  const globalTimeout = setTimeout(() => {
+    if (!finished) {
+      process.stderr.write(`[agy-companion] Global timeout (${timeoutMs}ms). Aborting.\n`);
+      shutdown(2);
+    }
+  }, timeoutMs);
+
+  function cleanupTemp() {
+    try {
+      if (tempSettingsCreated) {
+        fs.rmSync(tempWorkspace, { recursive: true, force: true });
+      } else {
+        fs.rmdirSync(tempWorkspace);
+      }
+    } catch (_) {}
+  }
+
+  function shutdown(code) {
+    if (finished) return;
+    finished = true;
+    clearTimeout(globalTimeout);
+    clearTimeout(initIdleTimer);
+    clearTimeout(responseIdleTimer);
+
+    try { ptyProc.write('\x03'); } catch (_) {}
+    setTimeout(() => {
+      try { ptyProc.kill(); } catch (_) {}
+
+      if (debug) {
+        const debugPath = path.resolve('agy-debug.log');
+        try { fs.writeFileSync(debugPath, rawBuffer, 'utf8'); } catch (_) {}
+        process.stderr.write(`[agy-companion] Debug log: ${debugPath}\n`);
+      }
+
+      cleanupTemp();
+      process.exit(code);
+    }, 500);
+  }
+
+  function deliverResponse() {
+    const responsePart = rawBuffer.slice(responseStartMark);
+    const stripped = stripAnsi(responsePart);
+    const response = extractResponse(stripped, responsePart, userPromptForFilter, effectivePromptForFilter);
+
+    if (response) {
+      outputResult(response);
+      shutdown(0);
+    } else {
+      const fullStripped = stripAnsi(rawBuffer);
+      const fallback = extractResponse(fullStripped, rawBuffer, userPromptForFilter, effectivePromptForFilter);
+      if (fallback) {
+        outputResult(fallback);
+      } else {
+        process.stderr.write('[agy-companion] No usable response received.\n');
+      }
+      shutdown(0);
+    }
+  }
+
+  function outputResult(text) {
+    if (jsonOutput) {
+      const result = { response: text, model: detectedModel || model, requestedModel: model, permissionMode };
+      process.stdout.write(JSON.stringify(result) + '\n');
+    } else {
+      process.stdout.write(text + '\n');
+    }
+  }
+
+  function sendQuestion() {
+    if (questionSent) return;
+    questionSent = true;
+    responseStartMark = rawBuffer.length;
+    process.stderr.write(`[agy-companion] Init complete. Sending question...\n`);
+    ptyProc.write(sanitizeForPty(effectivePrompt) + '\r');
+
+    responseIdleTimer = setTimeout(() => {
+      process.stderr.write(`[agy-companion] Response idle timeout. Extracting...\n`);
+      deliverResponse();
+    }, RESPONSE_IDLE_MS);
+  }
+
+  ptyProc.onData(chunk => {
+    rawBuffer += chunk;
+    const recentStripped = stripAnsi(rawBuffer.slice(-3000));
+
+    if (!questionSent && !finished) {
+      if (!detectedModel) {
+        const modelMatch = recentStripped.match(BANNER_MODEL_PATTERN);
+        if (modelMatch) {
+          detectedModel = modelMatch[0];
+          process.stderr.write(`[agy-companion] Detected model: ${detectedModel}\n`);
+        }
+      }
+
+      if (!trustHandled && TRUST_DIALOG_PATTERN.test(recentStripped)) {
+        trustHandled = true;
+        process.stderr.write(`[agy-companion] Trust dialog detected. Auto-confirming...\n`);
+        ptyProc.write('\r');
+      }
+
+      if (!startupComplete) {
+        if (STARTUP_DONE_PATTERNS.some(p => p.test(recentStripped))) {
+          startupComplete = true;
+          process.stderr.write(`[agy-companion] Startup complete. Waiting for init...\n`);
+          clearTimeout(initIdleTimer);
+          initIdleTimer = setTimeout(() => {
+            if (!initDone && !questionSent) {
+              initDone = true;
+              process.stderr.write(`[agy-companion] Init fallback timeout (${INIT_FALLBACK_MS}ms).\n`);
+              sendQuestion();
+            }
+          }, INIT_FALLBACK_MS);
+        }
+      }
+
+      if (startupComplete && !initDone) {
+        if (INIT_DONE_PATTERNS.some(p => p.test(recentStripped))) {
+          initDone = true;
+          clearTimeout(initIdleTimer);
+          process.stderr.write(`[agy-companion] Init detected. Brief pause...\n`);
+          setTimeout(sendQuestion, 1000);
+        } else {
+          clearTimeout(initIdleTimer);
+          initIdleTimer = setTimeout(() => {
+            if (!initDone && !questionSent) {
+              initDone = true;
+              process.stderr.write(`[agy-companion] Init idle timeout.\n`);
+              sendQuestion();
+            }
+          }, INIT_FALLBACK_MS);
+        }
+      }
+    } else if (questionSent && !finished) {
+      clearTimeout(responseIdleTimer);
+
+      const responseSoFar = stripAnsi(rawBuffer.slice(responseStartMark));
+      const respLines = responseSoFar.split('\n');
+      let seenQuestionEcho = false;
+      let responseComplete = false;
+      for (const line of respLines) {
+        const t = line.trim();
+        if (!seenQuestionEcho && userPromptForFilter && t.includes(userPromptForFilter.slice(0, 15))) {
+          seenQuestionEcho = true;
+        } else if (seenQuestionEcho && t === '>') {
+          responseComplete = true;
+          break;
+        }
+      }
+
+      if (responseComplete) {
+        responseIdleTimer = setTimeout(() => {
+          process.stderr.write(`[agy-companion] Response complete.\n`);
+          deliverResponse();
+        }, RESPONSE_DONE_IDLE_MS);
+      } else {
+        responseIdleTimer = setTimeout(() => {
+          process.stderr.write(`[agy-companion] Response idle timeout.\n`);
+          deliverResponse();
+        }, RESPONSE_IDLE_MS);
+      }
+    }
+  });
+
+  ptyProc.onExit(({ exitCode }) => {
+    if (!finished) {
+      if (questionSent) {
+        deliverResponse();
+      } else {
+        process.stderr.write('[agy-companion] agy exited before init completed.\n');
+        shutdown(exitCode ?? 1);
+      }
+    }
+  });
+}