companion-for-agy 1.2.0-alpha.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +73 -38
  2. package/CHANGELOG_de.md +97 -0
  3. package/README.md +72 -56
  4. package/README_de.md +99 -50
  5. package/README_es.md +154 -0
  6. package/README_ja.md +154 -0
  7. package/README_ru.md +154 -0
  8. package/README_zh-Hans.md +154 -0
  9. package/ROADMAP.md +46 -12
  10. package/package.json +11 -4
  11. package/src/agy-companion.mjs +307 -129
  12. package/src/locales.mjs +448 -0
package/CHANGELOG.md CHANGED
@@ -1,62 +1,97 @@
1
1
  # Changelog
2
2
 
3
+ ## [Unreleased]
4
+
5
+ ## [1.3.0] - 2026-06-07
6
+
7
+ ### Added
8
+ - CLI localization via `--lang <code>` and locale auto-detection.
9
+ - Supported CLI/documentation languages: English, German, Spanish, Simplified Chinese, Japanese, and Russian.
10
+ - New localization module `src/locales.mjs`.
11
+ - Translated README files: `README_de.md`, `README_es.md`, `README_zh-Hans.md`, `README_ja.md`, `README_ru.md`.
12
+ - German changelog: `CHANGELOG_de.md`.
13
+ - CLI regression tests for localized help and parsing errors.
14
+
15
+ ### Changed
16
+ - User-facing CLI strings are now read from locale maps instead of being hardcoded in `src/agy-companion.mjs`.
17
+ - `package.json` now includes all localized documentation files in the npm package.
18
+ - Documentation now distinguishes CLI output localization, documentation translation, and agy TUI recognition patterns.
19
+
20
+ ### Fixed
21
+ - Empty/non-extractable responses now exit nonzero instead of falling back to startup banner text or reporting success.
22
+ - Shutdown no longer force-kills the PTY when `Ctrl+C` already produced a clean exit, avoiding late `node-pty` cleanup stacktraces in successful runs.
23
+ - `researcher` and `read-only` permission presets now deny `command(*)` to prevent command-based writes.
24
+ - Unknown CLI options now fail fast; `--` can be used before prompts that start with a dash.
25
+ - Response color can now be overridden via `AGY_COMPANION_RESPONSE_RGB`.
26
+ - German trust/startup patterns, signal cleanup, dead-code cleanup, and one-character prompt/answer handling are covered by tests.
27
+ - agy v1.0.x can be used by omitting the model flag via `--no-model` or `AGY_COMPANION_NO_MODEL`.
28
+
29
+ ## [1.2.0] - 2026-06-07
30
+
31
+ ### Fixed (Bugsweep)
32
+ - **Security:** Stale temp workspace from crashed run with same PID could leak permissions to a new run; it is now cleaned on startup (`e8c5230`).
33
+ - Temp directory leak in sandbox/skip-permissions modes when no custom rules are set (`d406299`).
34
+ - Temp cleanup race on Windows: post-kill delay plus `rmSync` retries for CWD locks (`41412d6`).
35
+ - ConPTY text extraction: stale cursor position, bold SGR false positive, and too-narrow deduplication scope (`c2194bb`).
36
+ - `isNoiseLine` false positives for blockquotes (`>`) and lines containing the word "tokens" (`f6a8e7b`).
37
+
3
38
  ## [1.2.0-alpha.2] - 2026-06-07
4
39
 
5
40
  ### Changed
6
- - Brand ASCII banner aligned to left in READMEs
7
- - Switched image source to raw GitHub URLs to fix logo rendering on npmjs.com
41
+ - Brand ASCII banner aligned to the left in READMEs.
42
+ - Switched image source to raw GitHub URLs to fix logo rendering on npmjs.com.
8
43
 
9
44
  ### Fixed
10
- - Handled additional CLI tip noise (lines starting with `└`) and "Verifying..." lines in output parser
45
+ - Handled additional CLI tip noise (lines starting with `└`) and "Verifying..." lines in the output parser.
11
46
 
12
47
  ## [1.2.0-alpha.1] - 2026-06-07
13
48
 
14
49
  ### Changed
15
- - Package renamed to `companion-for-agy` (legal/trademark distancing via "for" pattern)
16
- - Added "Unofficial" disclaimer to README and package description
50
+ - Package renamed to `companion-for-agy` for legal/trademark distancing via the "for" pattern.
51
+ - Added "Unofficial" disclaimer to README and package description.
17
52
 
18
53
  ### Fixed
19
- - Short responses (≤2 chars like "4", "42", "ja") were incorrectly filtered as noise
20
- - Prompt-echo bug in `--no-tools` mode: the permission prefix ("IMPORTANT: Do not use...") was returned as the response instead of the actual answer
21
- - ConPTY space-loss in prompt echo: whitespace-normalized matching now handles "Donotuse" vs "Do not use"
54
+ - Short responses (2 or fewer characters like "4", "42", "ja") were incorrectly filtered as noise.
55
+ - Prompt-echo bug in `--no-tools` mode: the permission prefix was returned as the response instead of the actual answer.
56
+ - ConPTY space loss in prompt echo: whitespace-normalized matching now handles "Donotuse" versus "Do not use".
22
57
 
23
58
  ### Added
24
- - `stripPromptEcho()` — whitespace-tolerant prompt echo removal (word-by-word regex)
25
- - `extractResponse()` now accepts 4th parameter `effectiveFilter` for full prompt echo stripping
26
- - 5-phase state machine: Trust dialog auto-confirmation phase
27
- - Banner model detection: JSON reports actual model from agy's banner
28
- - 26 new tests (107 total): short answer extraction, prompt echo regression, stripPromptEcho unit tests
29
- - `companion-for-agy` CLI alias (alongside `agy-companion` for backward compatibility)
59
+ - `stripPromptEcho()` for whitespace-tolerant prompt echo removal.
60
+ - `extractResponse()` accepts a fourth parameter, `effectiveFilter`, for full prompt echo stripping.
61
+ - 5-phase state machine with a trust dialog auto-confirmation phase.
62
+ - Banner model detection: JSON reports the actual model from agy's banner.
63
+ - 26 new tests (107 total): short-answer extraction, prompt echo regression, and `stripPromptEcho` unit tests.
64
+ - `companion-for-agy` CLI alias alongside `agy-companion` for backward compatibility.
30
65
 
31
66
  ## [1.1.0] - 2026-06-06
32
67
 
33
68
  ### Changed
34
- - Cross-platform support: Windows, macOS, Linux (node-pty handles platform-specific PTY)
35
- - Auto-detection of agy binary via PATH, common install locations, env var fallback
36
- - node-pty loaded as standard npm dependency (no hardcoded path to gemini-cli internals)
37
- - Debug log writes to `./agy-debug.log` (CWD) instead of `~/.claude/scripts/`
38
- - CLI messages and usage text in English for international audience
39
- - Added English INIT_DONE_PATTERNS alongside German ones
40
- - Removed `"os": ["win32"]` restriction from package.json
69
+ - Cross-platform support: Windows, macOS, Linux (`node-pty` handles platform-specific PTYs).
70
+ - Auto-detection of the agy binary via PATH, common install locations, and environment variable fallback.
71
+ - `node-pty` loaded as a standard npm dependency, without a hardcoded path to gemini-cli internals.
72
+ - Debug log writes to `./agy-debug.log` instead of `~/.claude/scripts/`.
73
+ - CLI messages and usage text in English for an international audience.
74
+ - Added English `INIT_DONE_PATTERNS` alongside German ones.
75
+ - Removed the `"os": ["win32"]` restriction from `package.json`.
41
76
 
42
77
  ### Added
43
- - `findAgyPath()` exported function for programmatic agy detection
44
- - Test suite: 81 tests (unit, fixture, smoke) via `node:test`
45
- - `npm run deploy` and `npm run sync` scripts for local copy management
46
- - Comprehensive README with installation, troubleshooting, and usage docs
78
+ - Exported `findAgyPath()` for programmatic agy detection.
79
+ - Test suite: 81 tests (unit, fixture, smoke) via `node:test`.
80
+ - `npm run deploy` and `npm run sync` scripts for local copy management.
81
+ - Comprehensive README with installation, troubleshooting, and usage docs.
47
82
 
48
83
  ## [1.0.0] - 2026-06-06
49
84
 
50
- ### Hinzugefügt
51
- - ConPTY-basierter Wrapper für agy (Antigravity CLI)
52
- - ANSI-Color-basierte Response-Extraktion (RGB 232,234,237)
53
- - Fallback: Zeilen-basierte Noise-Filterung
54
- - 4-Phasen State-Machine (Startup → Init → Question → Response)
55
- - Adaptives Timing (10s während Generierung, 2.5s nach Abschluss)
56
- - Permission-System mit 5 Modi: sandbox, skip-permissions, no-tools, researcher, read-only
57
- - Custom allow/deny Regeln (kompatibel mit agys settings.json-Format)
58
- - JSON-Output-Modus (--json)
59
- - Konfigurierbare Pfade via Umgebungsvariablen
60
- - Prompt-Sanitisierung gegen PTY-Injection
61
- - Graceful Shutdown (Ctrl+C → Grace-Period → kill)
62
- - Debug-Modus mit PTY-Output-Log
85
+ ### Added
86
+ - ConPTY-based wrapper for agy (Antigravity CLI).
87
+ - ANSI-color-based response extraction (`RGB(232,234,237)`).
88
+ - Line-based noise-filter fallback.
89
+ - 4-phase state machine (startup, init, question, response).
90
+ - Adaptive timing: 10s during generation, 2.5s after completion.
91
+ - Permission system with 5 modes: sandbox, skip-permissions, no-tools, researcher, read-only.
92
+ - Custom allow/deny rules compatible with agy's `settings.json` format.
93
+ - JSON output mode (`--json`).
94
+ - Configurable paths via environment variables.
95
+ - Prompt sanitization against PTY injection.
96
+ - Graceful shutdown.
97
+ - Debug mode with PTY output log.
package/CHANGELOG_de.md ADDED
@@ -0,0 +1,97 @@
1
+ # Änderungsprotokoll
2
+
3
+ ## [Unveröffentlicht]
4
+
5
+ ## [1.3.0] - 2026-06-07
6
+
7
+ ### Hinzugefügt
8
+ - CLI-Lokalisierung über `--lang <Code>` und automatische Locale-Erkennung.
9
+ - Unterstützte CLI- und Dokumentationssprachen: Englisch, Deutsch, Spanisch, vereinfachtes Chinesisch, Japanisch und Russisch.
10
+ - Neues Lokalisierungsmodul `src/locales.mjs`.
11
+ - Übersetzte README-Dateien: `README_de.md`, `README_es.md`, `README_zh-Hans.md`, `README_ja.md`, `README_ru.md`.
12
+ - Deutsches Änderungsprotokoll: `CHANGELOG_de.md`.
13
+ - CLI-Regressionstests für lokalisierte Hilfe und lokalisierte Parsing-Fehler.
14
+
15
+ ### Geändert
16
+ - Benutzerseitige CLI-Texte werden nun aus Locale-Maps gelesen und nicht mehr direkt in `src/agy-companion.mjs` hartcodiert.
17
+ - `package.json` liefert alle lokalisierten Dokumentationsdateien im npm-Paket aus.
18
+ - Die Dokumentation trennt nun CLI-Lokalisierung, Dokumentationsübersetzung und agy-TUI-Erkennungsmuster.
19
+
20
+ ### Behoben
21
+ - Leere oder nicht extrahierbare Antworten führen nun zu einem Exit-Code ungleich Null, statt auf Startup-Banner-Text zurückzufallen oder Erfolg zu melden.
22
+ - Das Beenden erzwingt keinen PTY-Kill mehr, wenn `Ctrl+C` bereits zu einem sauberen Exit geführt hat. Das verhindert späte `node-pty`-Bereinigungs-Stacktraces bei erfolgreichen Läufen.
23
+ - Die Berechtigungs-Voreinstellungen `researcher` und `read-only` verbieten nun `command(*)`, um befehlsbasierte Schreibvorgänge zu verhindern.
24
+ - Unbekannte CLI-Optionen schlagen nun sofort fehl; `--` kann vor Prompts genutzt werden, die mit einem Bindestrich beginnen.
25
+ - Die Antwortfarbe kann über `AGY_COMPANION_RESPONSE_RGB` überschrieben werden.
26
+ - Deutsche Trust-/Startup-Muster, Signal-Bereinigung, Bereinigung von totem Code und Ein-Zeichen-Prompt/Antwort-Fälle sind durch Tests abgedeckt.
27
+ - agy v1.0.x kann genutzt werden, indem das Modell-Flag via `--no-model` oder `AGY_COMPANION_NO_MODEL` weggelassen wird.
28
+
29
+ ## [1.2.0] - 2026-06-07
30
+
31
+ ### Behoben (Bug-Sweep)
32
+ - **Sicherheit:** Ein veralteter temporärer Arbeitsbereich eines abgestürzten Laufs mit derselben PID konnte Berechtigungen an einen neuen Lauf übertragen; er wird nun beim Start bereinigt (`e8c5230`).
33
+ - Speicherleck des temporären Verzeichnisses im Sandbox- und Skip-Permissions-Modus, wenn keine benutzerdefinierten Regeln gesetzt sind (`d406299`).
34
+ - Race Condition bei der temporären Bereinigung unter Windows: Post-Kill-Verzögerung plus `rmSync`-Wiederholungen für CWD-Locks (`41412d6`).
35
+ - ConPTY-Textextraktion: veraltete Cursorposition, falsche Erkennung von fettem SGR und zu enger Entduplizierungsbereich (`c2194bb`).
36
+ - False Positives in `isNoiseLine` für Blockzitate (`>`) und Zeilen mit dem Wort "tokens" (`f6a8e7b`).
37
+
38
+ ## [1.2.0-alpha.2] - 2026-06-07
39
+
40
+ ### Geändert
41
+ - ASCII-Banner in den README-Dateien linksbündig ausgerichtet.
42
+ - Bildquelle auf rohe GitHub-URLs umgestellt, damit das Logo auf npmjs.com korrekt gerendert wird.
43
+
44
+ ### Behoben
45
+ - Zusätzliches CLI-Tipp-Rauschen (Zeilen mit `└`) und "Verifying..."-Zeilen im Ausgabe-Parser behandelt.
46
+
47
+ ## [1.2.0-alpha.1] - 2026-06-07
48
+
49
+ ### Geändert
50
+ - Paket in `companion-for-agy` umbenannt, um über das "for"-Muster rechtliche und markenbezogene Distanz zu schaffen.
51
+ - Hinweis "Inoffiziell" in README und Paketbeschreibung ergänzt.
52
+
53
+ ### Behoben
54
+ - Kurze Antworten (2 Zeichen oder weniger, z.B. "4", "42", "ja") wurden fälschlich als Rauschen gefiltert.
55
+ - Prompt-Echo-Bug im Modus `--no-tools`: Das Berechtigungspräfix wurde als Antwort zurückgegeben statt der eigentlichen Antwort.
56
+ - ConPTY-Leerzeichenverlust beim Prompt-Echo: Whitespace-normalisierter Abgleich verarbeitet nun "Donotuse" gegenüber "Do not use".
57
+
58
+ ### Hinzugefügt
59
+ - `stripPromptEcho()` für whitespace-tolerante Entfernung des Prompt-Echos.
60
+ - `extractResponse()` akzeptiert den vierten Parameter `effectiveFilter` für vollständiges Prompt-Echo-Stripping.
61
+ - 5-Phasen-State-Machine mit automatischer Bestätigung des Trust-Dialogs.
62
+ - Banner-Modellerkennung: JSON meldet das tatsächlich erkannte Modell aus agys Banner.
63
+ - 26 neue Tests (insgesamt 107): Extraktion kurzer Antworten, Prompt-Echo-Regression und Unit-Tests für `stripPromptEcho`.
64
+ - CLI-Alias `companion-for-agy` neben `agy-companion` für Abwärtskompatibilität.
65
+
66
+ ## [1.1.0] - 2026-06-06
67
+
68
+ ### Geändert
69
+ - Plattformübergreifende Unterstützung: Windows, macOS, Linux (`node-pty` verarbeitet plattformspezifische PTYs).
70
+ - Automatische Erkennung der agy-Binärdatei über PATH, übliche Installationsorte und Umgebungsvariablen.
71
+ - `node-pty` wird als normale npm-Abhängigkeit geladen, ohne hartcodierten Pfad zu gemini-cli-Interna.
72
+ - Debug-Log schreibt nach `./agy-debug.log` statt nach `~/.claude/scripts/`.
73
+ - CLI-Nachrichten und Nutzungstexte auf Englisch für ein internationales Publikum.
74
+ - Englische `INIT_DONE_PATTERNS` neben deutschen Patterns ergänzt.
75
+ - Einschränkung `"os": ["win32"]` aus `package.json` entfernt.
76
+
77
+ ### Hinzugefügt
78
+ - Exportierte Funktion `findAgyPath()` für programmatische agy-Erkennung.
79
+ - Testsuite: 81 Tests (Unit, Fixture, Smoke) via `node:test`.
80
+ - Skripte `npm run deploy` und `npm run sync` für lokale Kopieverwaltung.
81
+ - Umfassende README mit Installation, Fehlerbehebung und Nutzung.
82
+
83
+ ## [1.0.0] - 2026-06-06
84
+
85
+ ### Hinzugefügt
86
+ - ConPTY-basierter Wrapper für agy (Antigravity CLI).
87
+ - ANSI-farbbasierte Antwortextraktion (`RGB(232,234,237)`).
88
+ - Zeilenbasierter Noise-Filter-Fallback.
89
+ - 4-Phasen-State-Machine (Startup, Init, Frage, Antwort).
90
+ - Adaptives Timing: 10s während Generierung, 2.5s nach Abschluss.
91
+ - Berechtigungssystem mit 5 Modi: sandbox, skip-permissions, no-tools, researcher, read-only.
92
+ - Benutzerdefinierte Allow-/Deny-Regeln, kompatibel mit agys `settings.json`-Format.
93
+ - JSON-Ausgabemodus (`--json`).
94
+ - Konfigurierbare Pfade über Umgebungsvariablen.
95
+ - Prompt-Sanitisierung gegen PTY-Injection.
96
+ - Graceful Shutdown.
97
+ - Debug-Modus mit PTY-Output-Log.
package/README.md CHANGED
@@ -6,29 +6,35 @@
6
6
 
7
7
  [![npm](https://img.shields.io/npm/v/companion-for-agy)](https://www.npmjs.com/package/companion-for-agy)
8
8
  [![CI](https://github.com/dev-bricks/companion-for-agy/actions/workflows/tests.yml/badge.svg)](https://github.com/dev-bricks/companion-for-agy/actions/workflows/tests.yml)
9
+ [![English](https://img.shields.io/badge/lang-English-blue)](README.md)
9
10
  [![Deutsch](https://img.shields.io/badge/lang-Deutsch-blue)](README_de.md)
11
+ [![Español](https://img.shields.io/badge/lang-Espa%C3%B1ol-blue)](README_es.md)
12
+ [![简体中文](https://img.shields.io/badge/lang-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-blue)](README_zh-Hans.md)
13
+ [![日本語](https://img.shields.io/badge/lang-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](README_ja.md)
14
+ [![Русский](https://img.shields.io/badge/lang-%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-blue)](README_ru.md)
10
15
 
11
- > **Unofficial** — not affiliated with or endorsed by Google.
16
+ > **Unofficial** - not affiliated with or endorsed by Google.
12
17
 
13
18
  PTY-based wrapper for **agy** (Antigravity CLI / Gemini CLI) that captures Gemini responses from subprocesses.
14
19
 
15
20
  ## Problem
16
21
 
17
- `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:
22
+ `agy -p` (print mode) exits with code 0 but writes no response to stdout. Instead, the TUI text-drip renderer (`text_drip.go`) writes to the terminal buffer. Known upstream issues:
18
23
 
19
24
  - [antigravity-cli#76](https://github.com/google-antigravity/antigravity-cli/issues/76)
20
25
  - [gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)
21
26
  - [antigravity-cli#115](https://github.com/google-antigravity/antigravity-cli/issues/115)
22
27
 
23
- This means no other agent (Claude Code, Codex, CI/CD) can programmatically read agy's responses.
28
+ That means other agents such as Claude Code, Codex, or CI/CD scripts cannot programmatically read agy's responses.
24
29
 
25
30
  ## Solution
26
31
 
27
- `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.
32
+ `companion-for-agy` starts 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 currently uses `RGB(232,234,237)`, so the wrapper tracks ANSI color state and collects only text in that color.
28
33
 
29
- > **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:
30
- > - **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).
31
- > - 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.
34
+ > **Platform note:** 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 through `node-pty`, but the exact response color still needs independent verification there.
35
+ >
36
+ > - **agy v1.0.x** (Homebrew `antigravity-cli`) does not support `--model`; use `--no-model` or `AGY_COMPANION_NO_MODEL=1`.
37
+ > - If color extraction returns an empty result, run with `--debug` and inspect `agy-debug.log`.
32
38
 
33
39
  ## Installation
34
40
 
@@ -40,21 +46,15 @@ npm install -g companion-for-agy
40
46
 
41
47
  - **Node.js >= 18**
42
48
  - **agy** ([Gemini CLI](https://github.com/google-gemini/gemini-cli)) installed and authenticated
43
- - **C/C++ build tools** for `node-pty` native compilation:
44
- - **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) + Python 3
49
+ - **C/C++ build tools** for native `node-pty` compilation:
50
+ - **Windows:** Visual Studio Build Tools + Python 3
45
51
  - **macOS:** `xcode-select --install`
46
52
  - **Linux:** `sudo apt install build-essential python3` (Debian/Ubuntu)
47
53
 
48
- ### Troubleshooting `node-pty` build errors
49
-
50
- If `npm install` fails with native compilation errors:
54
+ If native compilation fails, run:
51
55
 
52
56
  ```bash
53
- # All platforms: rebuild native modules
54
57
  npm rebuild node-pty
55
-
56
- # Windows: if cl.exe is not found, install Visual Studio Build Tools
57
- # then open "Developer Command Prompt" or run from "x64 Native Tools"
58
58
  ```
59
59
 
60
60
  ## Usage
@@ -67,17 +67,17 @@ companion-for-agy [options] "prompt"
67
67
 
68
68
  | Flag | Description |
69
69
  |------|-------------|
70
- | `--sandbox` | Sandbox mode (default) — tools in container |
70
+ | `--sandbox` | Sandbox mode (default), tools in container |
71
71
  | `--skip-permissions` | All tools without confirmation (YOLO) |
72
- | `--no-tools` | Pure chat — no tool execution |
73
- | `--researcher` | Web search allowed, no file changes |
74
- | `--read-only` | Read-only, no modifications |
72
+ | `--no-tools` | Pure chat, no tool execution |
73
+ | `--researcher` | Web/search research allowed, shell commands and file changes denied |
74
+ | `--read-only` | File reads allowed, shell commands and modifications denied |
75
75
 
76
76
  ### Custom Rules
77
77
 
78
78
  ```bash
79
79
  --allow "read_file(/path)" # Allowlist rule (repeatable)
80
- --deny "command(rm)" # Denylist rule (repeatable)
80
+ --deny "command(rm)" # Denylist rule (repeatable)
81
81
  ```
82
82
 
83
83
  Formats match agy's own permission system (`settings.json`).
@@ -87,72 +87,88 @@ Formats match agy's own permission system (`settings.json`).
87
87
  | Flag | Description |
88
88
  |------|-------------|
89
89
  | `--model <model>` | Gemini model (default: `gemini-3.5-flash`) |
90
- | `--timeout <ms>` | Timeout in ms (default: 120000) |
90
+ | `--no-model` | Do not pass `--model` to agy; useful for agy v1.0.x |
91
+ | `--timeout <ms>` | Timeout in ms (default: `120000`) |
91
92
  | `--json` | Output as JSON object |
92
93
  | `--debug` | Save raw PTY output to `agy-debug.log` |
94
+ | `--lang <code>` | CLI output language: `en`, `de`, `es`, `zh-Hans`, `ja`, `ru` |
95
+ | `--` | Stop option parsing; use before prompts that start with `-` |
93
96
 
94
97
  ### Environment Variables
95
98
 
96
99
  | Variable | Description |
97
100
  |----------|-------------|
98
- | `AGY_COMPANION_AGY_PATH` | Path to agy binary (auto-detected if not set) |
101
+ | `AGY_COMPANION_AGY_PATH` | Path to agy binary (auto-detected if unset) |
99
102
  | `AGY_PATH` | Alternative path to agy binary |
103
+ | `AGY_COMPANION_NO_MODEL` | Set to `1`, `true`, or `yes` to omit `--model` |
104
+ | `AGY_COMPANION_RESPONSE_RGB` | Override response color as `R,G,B` or `R;G;B` |
100
105
 
101
106
  ### Examples
102
107
 
103
108
  ```bash
104
- # Simple question
105
109
  companion-for-agy "What is the capital of Bavaria?"
106
-
107
- # As advisor (no tool use)
108
110
  companion-for-agy --no-tools "Review this code: ..."
109
-
110
- # Web research
111
111
  companion-for-agy --researcher "Latest info on Node.js 24"
112
-
113
- # Read-only with additional git permission
114
112
  companion-for-agy --read-only --allow "command(git log)" "prompt"
115
-
116
- # JSON output for programmatic use
117
113
  companion-for-agy --json --model gemini-3.5-pro "prompt"
118
- # → {"response":"...","model":"Gemini 3.5 Pro (High)","requestedModel":"gemini-3.5-pro","permissionMode":"sandbox"}
114
+ companion-for-agy --no-model "prompt"
115
+ companion-for-agy --lang de --help
116
+ companion-for-agy --no-tools -- "-dash-prefixed prompt"
119
117
  ```
120
118
 
121
- > **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`.
119
+ JSON output includes `response`, `model`, `requestedModel`, and `permissionMode`. `model` is detected from agy's banner when possible and falls back to `requestedModel`.
120
+
121
+ ## Internationalization Scope
122
+
123
+ There are three separate i18n surfaces:
124
+
125
+ 1. **companion-for-agy CLI output:** help text, errors, and status lines produced by this wrapper.
126
+ 2. **Documentation:** README, contributing guide, changelog, and examples.
127
+ 3. **agy TUI recognition patterns:** internal regexes that detect agy's trust dialog, startup readiness, init completion, and response completion.
128
+
129
+ Local Windows checks showed that `agy --help` stayed English under `LANG=en_US`, `de_DE`, `ja_JP`, and `zh_CN`. That suggests agy's CLI help is currently English-only, but it does not prove every TUI dialog, future agy release, plugin, or OS-specific flow will stay English.
130
+
131
+ Planned user-facing languages:
132
+
133
+ | Code | Language | Scope |
134
+ |------|----------|-------|
135
+ | `en` | English | Default CLI and canonical docs |
136
+ | `de` | German | Translated docs and CLI output |
137
+ | `es` | Spanish | Translated docs and CLI output |
138
+ | `zh-Hans` | Simplified Chinese | Translated docs and CLI output |
139
+ | `ja` | Japanese | Translated docs and CLI output |
140
+ | `ru` | Russian | Translated docs and CLI output |
141
+
142
+ Recognition patterns are not blindly translated. English stays the baseline; non-English patterns are added only when agy actually emits those strings or a stable upstream string is documented.
122
143
 
123
144
  ## How It Works
124
145
 
125
- ```
126
- ┌────────────────────┐ PTY ┌─────────────┐
127
- │ companion-for-agy │ ─────────────▸ │ agy │
128
- │ (Node.js) │ ◂────────────── │ (Go TUI) │
129
- │ │ ANSI stream │ │
130
- │ Color-Based │ │ text_drip.go│
131
- │ Extraction │ │ RGB(232,234,│
132
- │ │ │ 237) │
133
- └────────┬───────────┘ └─────────────┘
134
- │
135
- ▼ stdout
136
- Response text
146
+ ```text
147
+ companion-for-agy (Node.js)
148
+ -> starts agy in a PTY
149
+ -> detects trust/startup/init states
150
+ -> sends the prompt
151
+ -> captures ANSI response-color segments
152
+ -> writes response text to stdout
137
153
  ```
138
154
 
139
- **5-Phase State Machine:**
155
+ **5-phase state machine:**
140
156
 
141
- 1. **Trust** — detect and auto-confirm workspace trust dialog
142
- 2. **Startup** — detect main UI readiness (`? for shortcuts`)
143
- 3. **Init** — wait for GEMINI.md initialization (pattern matching or 20s fallback)
144
- 4. **Question** — send prompt, set response marker
145
- 5. **Response** — read response via ANSI color extraction, adaptive idle timer
157
+ 1. **Trust:** detect and auto-confirm workspace trust dialog
158
+ 2. **Startup:** detect main UI readiness (`? for shortcuts`)
159
+ 3. **Init:** wait for initialization, with timeout fallback
160
+ 4. **Question:** send prompt and mark response start
161
+ 5. **Response:** extract response via ANSI color and adaptive idle timers
146
162
 
147
163
  ## Use Cases
148
164
 
149
- - **Multi-agent orchestration**: Claude Code, Codex, or other agents querying Gemini via agy
150
- - **CI/CD pipelines**: automated Gemini queries in build scripts
151
- - **Scripting**: any scenario where agy's response needs to be captured as text
165
+ - Multi-agent orchestration: Claude Code, Codex, or other agents querying Gemini via agy
166
+ - CI/CD scripts that need text output from agy
167
+ - Local automation where agy's TUI response must be captured as stdout
152
168
 
153
169
  ## Background
154
170
 
155
- 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.
171
+ This tool was built because three CLI agents - Claude Code, Codex, and agy - need to call each other as fallback advisors. Claude to Codex and agy to Claude/Codex already worked; Claude to agy was blocked by the TUI stdout bug.
156
172
 
157
173
  ## License
158
174