ccx-relay 1.5.0

package/.env.example

@@ -0,0 +1,12 @@
+# Google Gemini API key (required).
+# Get one at https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+
+# Gemini model to use for prompt rewriting (optional).
+# Default: gemini-3.5-flash
+GEMINI_MODEL=gemini-3.5-flash
+
+# Trailing marker that triggers "enhance current line" when you press Enter
+# (optional). Type your prompt, append this marker, then press Enter once to
+# enhance (not submit) - press Enter again to actually submit. Default: ;;
+CCX_MARKER=;;

package/README.md

@@ -0,0 +1,171 @@
+# ccx
+
+A transparent PTY wrapper for [Claude Code](https://docs.anthropic.com/claude/docs/claude-code) (or any interactive
+CLI) that lets you refine your prompt with Gemini AI before you submit it — without leaving your normal terminal
+session.
+
+Run `ccx claude` instead of `claude`. Everything looks and behaves like a normal Claude Code session. When you want a
+rough line cleaned up, append a trailing marker (default `;;`) and press Enter once — `ccx` sends what you typed
+(minus the marker) to Gemini, gets back a grammatically corrected / clearer rewrite of the same intent, and swaps it
+in-place on the line, as if you'd typed the better version yourself, without submitting it yet. Review it, then press
+Enter again as usual to actually submit.
+
+This marker-based trigger (rather than a keyboard shortcut) is deliberate: a hotkey has to survive three independent
+layers of keybinding claims — the OS/global-hotkey tools, the terminal app (VS Code and its extensions), and the
+wrapped CLI's own input handling — and on a sufficiently customized machine, every `Ctrl`/`Alt` combination worth
+trying can already be spoken for by one of them. Plain typed text has no such competition.
+
+## Prerequisites
+
+- **Node.js 18+** (needed for the built-in `fetch` used to call the Gemini API).
+- **A Gemini API key** — get one at https://aistudio.google.com/apikey. As of mid-2026, Google issues new keys as
+  "Auth keys" starting with `AQ.` (the older `AIza`-prefixed "Standard" keys are being phased out through
+  September 2026). `ccx` sends the key via the `x-goog-api-key` header, which works for both key types.
+- **Windows only:** `node-pty` is a native module and needs to be compiled during `npm install`. Make sure you have:
+  - Visual Studio Build Tools with the "Desktop development with C++" workload, and
+  - Python 3.x on your PATH.
+
+  If `npm install` fails while building `node-pty`, install the above and run `npm rebuild node-pty`.
+
+## Install
+
+```bash
+npm install -g ccx-relay
+```
+
+## Setup
+
+Run the one-time setup wizard:
+
+```bash
+ccx init
+```
+
+This will prompt for your Gemini API key (get one at https://aistudio.google.com/apikey), validate it, let you pick a model, and save config to your user directory (`%APPDATA%\ccx\config.json` on Windows, `~/.config/ccx/config.json` on macOS/Linux). Config survives npm upgrades.
+
+Other init commands:
+
+```bash
+ccx init --show    # print current config (key masked)
+ccx init --reset   # wipe config and start over
+```
+
+### Environment variable override
+
+You can skip `ccx init` and set env vars directly (useful for CI):
+
+```bash
+export GEMINI_API_KEY=AIza...
+export GEMINI_MODEL=gemini-2.5-flash   # optional
+export CCX_MARKER=;;                   # optional
+export CCX_TIMEOUT=8                   # optional, seconds
+```
+
+## Usage
+
+```bash
+ccx claude          # launch Claude Code behind the ccx relay
+ccx claude --resume  # any extra args are passed straight through
+ccx bash             # or any other command — ccx just wraps argv
+```
+
+While the wrapped process is running:
+
+- Type normally — every keystroke is forwarded to the child process exactly as if `ccx` weren't there.
+- **Trigger with marker:** type `;;` at the end of your line, then press **Enter**. ccx enhances the line and replaces it in place — this first Enter does *not* submit.
+- **Trigger with shortcut:** press **Alt+M** at any point on a non-empty line to enhance immediately without a marker.
+- After enhancement, a Braille spinner animates while Gemini rewrites your prompt, then shows `✓ Enhanced` on success or `✗ error message` on failure.
+- Review the rewritten line, then press **Enter** to submit it to the child process.
+- A plain line with no trigger submits immediately on Enter, exactly as if `ccx` weren't there.
+- Arrow keys, Ctrl+C, and other control sequences pass through untouched.
+
+### Changing the marker
+
+Change `CCX_MARKER` via `ccx init` or env var (default `;;`). No source changes needed.
+
+## Testing it locally
+
+1. `npm install`
+2. `npm run test` — runs `node --check` against the CLI entry point to catch syntax errors.
+3. `npm link`
+4. Set up `.env` with a real `GEMINI_API_KEY`.
+5. Sanity-check the relay mechanics with a safe command first, before pointing it at `claude`:
+
+   ```bash
+   ccx cmd        # Windows Command Prompt
+   ccx powershell # or PowerShell
+   ```
+
+   You should see a completely normal shell. Type a sentence with a typo, e.g. `pls fix teh bug in server.js;;`,
+   then press **Enter**. You should see `[ccx] enhancing...` flash briefly, then the line rewritten in place
+   (e.g. `Please fix the bug in server.js`) with nothing submitted yet. Press Enter again to run it as a normal
+   shell command.
+
+6. Once the mechanics check out, run it against the real target:
+
+   ```bash
+   ccx claude
+   ```
+
+## Known limitations
+
+- **Works best for single-line prompts typed straight through.** The line buffer is a plain JS string built up as
+  you type; it does not model cursor position.
+- **Heavy mid-line editing via arrow keys is not fully tracked.** Escape sequences (arrow keys, Home/End, etc.) are
+  detected and forwarded to the child untouched so navigation still *works* visually, but `ccx`'s internal buffer
+  does not move its own "cursor" — it only appends on printable input and pops on backspace. If you arrow back into
+  the middle of a line and start editing there, the buffer sent to Gemini (and the backspace count used to erase the
+  line) can drift out of sync with what's actually on screen. Worth testing carefully before relying on it for
+  heavily-edited multi-line pastes.
+- **Byte-wise, not codepoint-wise.** Input is processed one byte at a time; multi-byte UTF-8 characters (accents,
+  emoji, non-Latin scripts) may not round-trip through the buffer correctly, though they are still forwarded to the
+  child untouched when you're not invoking the hotkey.
+- **Status line display is best-effort.** `ccx` uses ANSI save/restore-cursor sequences to show and clear the
+  `[ccx] enhancing...` message on its own line. This works in standard ANSI/VT terminals (including the VS Code
+  integrated terminal) but isn't guaranteed on every terminal emulator.
+- **The marker itself is reserved.** If you genuinely need a prompt to end with `;;` literally, either add a
+  trailing space after it or change `CCX_MARKER` to something you don't otherwise type.
+
+## Windows-specific notes
+
+- **`.cmd`/`.bat` shims:** `node-pty` spawns processes via Windows' `CreateProcess`, which cannot directly execute
+  `.cmd`/`.bat` files (this is how `claude` and many other npm-installed global CLIs are shimmed on Windows). `ccx`
+  works around this by routing the target command through `cmd.exe /c` on Windows. You shouldn't need to do anything
+  differently — `ccx claude` just works — but if you add your own wrapped commands, keep in mind they're run via
+  `cmd.exe`.
+- **ConPTY vs. WSL:** on native Windows, `node-pty` uses ConPTY (Windows' native pseudoconsole API). This is
+  different from running inside WSL, where `node-pty` behaves like it does on Linux/macOS (real PTYs). Resize
+  events, signal delivery, and raw-mode behavior can differ subtly between the two — if you run `ccx` inside a WSL
+  terminal instead of a native Windows one, treat it as a separate environment to re-test.
+- **"win32-input-mode" can replace plain keys with escape sequences.** Some CLIs (Claude Code included) enable a
+  ConPTY/Windows Terminal feature called win32-input-mode on startup, for full keyboard fidelity (e.g. to
+  distinguish Enter from Shift+Enter). Once enabled, the *real* host terminal stops sending some keys as plain
+  bytes and instead encodes them as `ESC[Vk;Sc;Uc;Kd;Cs;Rc_` (virtual-key code, scan code, Unicode char, key
+  down/up flag, control-key state, repeat count) — this was observed for both Enter (`Vk=13`) and Backspace
+  (`Vk=8`) while wrapping `claude`, arriving as a pair of sequences (key-down then key-up) in a single stdin read.
+  `ccx` decodes this format specifically to recognize Enter and Backspace; if you see other keys behaving oddly
+  when wrapping a different CLI on Windows, they may need the same treatment — check `parseWin32InputSeq` in
+  `bin/ccx.js`.
+- **Ctrl+C:** in raw mode with ConPTY's virtual-terminal input enabled, Ctrl+C arrives as byte `0x03` through stdin
+  (like POSIX) rather than as a Windows console control event, so it's forwarded to the child like any other
+  keystroke rather than killing `ccx` itself.
+
+## Publishing
+
+The npm package is named `ccx-relay` (`ccx` itself is already taken on npm). The command you run stays `ccx` — that
+comes from the `bin` field, not the package name — so nothing about day-to-day usage changes.
+
+```bash
+npm login
+npm publish
+```
+
+For subsequent releases:
+
+```bash
+npm version patch   # or minor / major
+npm publish
+```
+
+`npm version patch` bumps the version in `package.json`, creates a git commit and tag (if this is a git repo), which
+you can then push along with the new publish.

package/bin/ccx-init.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'node:readline';
+import { rmSync, existsSync } from 'node:fs';
+import { load, save, configPath } from '../src/config.js';
+import { enhance } from '../src/gemini.js';
+
+const args = process.argv.slice(2);
+
+// Hidden input helper for API key
+async function promptHidden(question) {
+  return new Promise(resolve => {
+    process.stdout.write(question);
+    const rl = createInterface({ input: process.stdin, output: null, terminal: false });
+    if (process.stdin.isTTY) process.stdin.setRawMode(true);
+    let input = '';
+    process.stdin.on('data', function onData(buf) {
+      for (let i = 0; i < buf.length; i++) {
+        const byte = buf[i];
+        if (byte === 0x0d || byte === 0x0a) {
+          if (process.stdin.isTTY) process.stdin.setRawMode(false);
+          process.stdout.write('\n');
+          process.stdin.removeListener('data', onData);
+          rl.close();
+          resolve(input);
+          return;
+        } else if (byte === 0x7f || byte === 0x08) {
+          if (input.length > 0) { input = input.slice(0, -1); process.stdout.write('\b \b'); }
+        } else if (byte === 0x03) {
+          process.exit(0);
+        } else if (byte >= 0x20) {
+          input += String.fromCharCode(byte);
+          process.stdout.write('*');
+        }
+      }
+    });
+  });
+}
+
+// Regular prompt helper
+async function prompt(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+// Mask API key: show first 6 chars + ****...
+function maskKey(key) {
+  if (!key) return '(not set)';
+  if (key.length <= 6) return key + '****...';
+  return key.slice(0, 6) + '****...';
+}
+
+// Show current config
+function showConfig() {
+  const config = load();
+  const path = configPath();
+
+  console.log(`Config: ${path}\n`);
+  console.log(`  geminiApiKey:   ${maskKey(config.geminiApiKey)}`);
+  console.log(`  geminiModel:    ${config.geminiModel}`);
+  console.log(`  marker:         ${config.marker}`);
+  console.log(`  timeoutSeconds: ${config.timeoutSeconds}`);
+}
+
+// Reset config
+function resetConfig() {
+  const path = configPath();
+
+  if (existsSync(path)) {
+    rmSync(path);
+    console.log('Config reset. Run `ccx init` to set up again.');
+  } else {
+    console.log('No config file found — nothing to reset.');
+  }
+}
+
+// Interactive wizard
+async function runWizard() {
+  console.log('\n  Welcome to ccx setup\n');
+
+  // Step 1: Prompt for API key
+  const key = await promptHidden('  API key: ');
+  if (!key) {
+    console.log('No key entered. Aborting.');
+    process.exit(1);
+  }
+
+  // Step 2: Test the key
+  process.stdout.write('  Testing key... ');
+  try {
+    await enhance('hello', { geminiApiKey: key, geminiModel: 'gemini-2.5-flash', timeoutSeconds: 10 });
+    console.log('\x1b[32m✓ Valid\x1b[0m');
+  } catch (err) {
+    console.log(`\x1b[31m✗ Invalid key\x1b[0m — ${err.message}`);
+    process.exit(1);
+  }
+
+  // Step 3: Model picker
+  const models = [
+    'gemini-2.5-flash',
+    'gemini-1.5-flash',
+    'gemini-2.5-pro'
+  ];
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log('');
+  console.log('  Model:');
+  console.log('  1) gemini-2.5-flash (default)');
+  console.log('  2) gemini-1.5-flash');
+  console.log('  3) gemini-2.5-pro');
+
+  const modelChoice = await prompt(rl, '  Choice [1]: ');
+  const modelIndex = modelChoice.trim() === '' || modelChoice.trim() === '1' ? 0 :
+                    modelChoice.trim() === '2' ? 1 :
+                    modelChoice.trim() === '3' ? 2 : 0;
+  const model = models[modelIndex];
+
+  // Step 4: Trigger marker
+  const markerAnswer = await prompt(rl, '  Trigger marker [;;]: ');
+  const marker = markerAnswer.trim() || ';;';
+
+  // Step 5: Timeout seconds
+  const timeoutAnswer = await prompt(rl, '  Timeout seconds [8]: ');
+  const timeoutSeconds = timeoutAnswer.trim() === '' ? 8 : (parseInt(timeoutAnswer, 10) || 8);
+
+  rl.close();
+
+  // Step 6: Save config
+  save({ geminiApiKey: key, geminiModel: model, marker, timeoutSeconds });
+
+  // Step 7: Success message
+  console.log(`\n  Config saved to ${configPath()}`);
+  console.log('  Run `ccx claude` to start.\n');
+}
+
+// Main dispatch
+if (args.length === 0) {
+  runWizard();
+} else if (args[0] === '--show') {
+  showConfig();
+} else if (args[0] === '--reset') {
+  resetConfig();
+} else {
+  console.error(`Unknown command: ${args[0]}`);
+  process.exit(1);
+}

package/bin/ccx.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+import { load } from '../src/config.js';
+import { enhance, RateLimitError, AuthError, ModelError, TimeoutError, NetworkError } from '../src/gemini.js';
+import { start as spinnerStart, stop as spinnerStop, clear as spinnerClear } from '../src/ui.js';
+import { createInputHandler } from '../src/input.js';
+
+let pty;
+try {
+  pty = (await import('node-pty')).default;
+} catch (err) {
+  process.stderr.write(
+    '[ccx] Failed to load node-pty. On Windows install "Desktop development with C++"\n' +
+    'workload (Visual Studio Build Tools) and Python, then run: npm rebuild node-pty\n' +
+    `Original error: ${err.message}\n`
+  );
+  process.exit(1);
+}
+
+const config = load();
+
+if (!config.geminiApiKey) {
+  process.stderr.write('[ccx] No API key found. Run `ccx init` to set up.\n');
+  process.exit(1);
+}
+
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+  process.stderr.write('[ccx] ccx must be run in an interactive terminal.\n');
+  process.exit(1);
+}
+
+const argv      = process.argv.slice(2);
+const targetCmd = argv[0] || 'claude';
+const targetArgs= argv.slice(1);
+
+const isWindows = process.platform === 'win32';
+const shellFile = isWindows ? (process.env.COMSPEC || 'cmd.exe') : targetCmd;
+const shellArgs = isWindows ? ['/d', '/s', '/c', [targetCmd, ...targetArgs].join(' ')] : targetArgs;
+
+const ptyProcess = pty.spawn(shellFile, shellArgs, {
+  name: 'xterm-color',
+  cols: process.stdout.columns || 80,
+  rows: process.stdout.rows   || 24,
+  cwd:  process.cwd(),
+  env:  process.env,
+});
+
+ptyProcess.onData(data => process.stdout.write(data));
+
+process.stdout.on('resize', () => {
+  ptyProcess.resize(process.stdout.columns, process.stdout.rows);
+});
+
+process.stdin.setRawMode(true);
+process.stdin.resume();
+
+const handler = createInputHandler({
+  marker: config.marker,
+
+  onEnhance: async (line) => {
+    // line may include trailing marker (;;) for the ;; trigger — strip it
+    const toSend = line.endsWith(config.marker) ? line.slice(0, -config.marker.length) : line;
+    handler.setBusy(true);
+    spinnerStart();
+    let improved;
+    try {
+      improved = await enhance(toSend, config);
+    } catch (err) {
+      let msg = 'Enhancement failed';
+      if (err instanceof RateLimitError) msg = 'Quota exceeded';
+      else if (err instanceof AuthError)  msg = 'Invalid key — run ccx init';
+      else if (err instanceof ModelError) msg = 'Model not found — run ccx init';
+      else if (err instanceof TimeoutError) msg = `Timed out after ${config.timeoutSeconds}s — original restored`;
+      else if (err instanceof NetworkError) msg = 'No connection — original restored';
+      await spinnerStop('error', msg);
+      // Erase full echoed text (including marker if present), restore clean original
+      ptyProcess.write(Buffer.alloc(line.length, 0x7f));
+      ptyProcess.write(toSend);
+      handler.setBusy(false);
+      return;
+    }
+    await spinnerStop('success', 'Enhanced');
+    // Erase full echoed text (including marker), write improved
+    ptyProcess.write(Buffer.alloc(line.length, 0x7f));
+    ptyProcess.write(improved);
+    handler.setBusy(false);
+  },
+
+  onSubmit: (_line) => {
+    // Enter already forwarded by input.js passthrough
+  },
+
+  onPassthrough: (chunk) => ptyProcess.write(chunk),
+
+  onCtrlC: () => {
+    spinnerClear();
+    handler.reset();
+  },
+});
+
+process.stdin.on('data', chunk => handler.processChunk(chunk));
+
+function cleanupAndExit(code) {
+  try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch (_) {}
+  process.exit(code == null ? 0 : code);
+}
+
+ptyProcess.onExit(({ exitCode }) => cleanupAndExit(exitCode));
+process.on('SIGINT', () => {});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "type": "module",
+  "name": "ccx-relay",
+  "version": "1.5.0",
+  "description": "Transparent PTY wrapper for Claude Code (or any CLI) that lets you refine your prompt with Gemini AI before submitting it, without leaving your terminal session.",
+  "main": "bin/ccx.js",
+  "bin": {
+    "ccx": "bin/ccx.js",
+    "ccx-init": "bin/ccx-init.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "cli",
+    "claude",
+    "claude-code",
+    "gemini",
+    "pty",
+    "terminal",
+    "ai",
+    "prompt-engineering"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unhiredcoder/ccx-relay.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "node-pty": "^1.0.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const defaults = {
+  geminiApiKey: null,
+  geminiModel: 'gemini-2.5-flash',
+  marker: ';;',
+  timeoutSeconds: 8,
+};
+
+/**
+ * Returns the path to the config.json file.
+ * Windows: %APPDATA%/ccx/config.json
+ * macOS/Linux: ~/.config/ccx/config.json
+ */
+export function configPath() {
+  let configDir;
+
+  if (process.platform === 'win32') {
+    configDir = path.join(
+      process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+      'ccx'
+    );
+  } else {
+    configDir = path.join(
+      process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+      'ccx'
+    );
+  }
+
+  return path.join(configDir, 'config.json');
+}
+
+/**
+ * Loads user configuration from multiple sources with priority:
+ * 1. Environment variables
+ * 2. config.json file (if exists)
+ * 3. Hardcoded defaults
+ */
+export function load() {
+  const result = { ...defaults };
+
+  // Layer 2: Read from config.json if it exists
+  try {
+    const configFilePath = configPath();
+    if (fs.existsSync(configFilePath)) {
+      const fileContent = fs.readFileSync(configFilePath, 'utf8');
+      const fileConfig = JSON.parse(fileContent);
+      Object.assign(result, fileConfig);
+    }
+  } catch (error) {
+    // If file doesn't exist or fails to parse, use defaults silently
+  }
+
+  // Layer 1: Environment variables override everything
+  if (process.env.GEMINI_API_KEY) {
+    result.geminiApiKey = process.env.GEMINI_API_KEY;
+  }
+  if (process.env.GEMINI_MODEL) {
+    result.geminiModel = process.env.GEMINI_MODEL;
+  }
+  const rawMarker = (process.env.CCX_MARKER !== undefined ? process.env.CCX_MARKER : null) || result.marker || defaults.marker;
+  result.marker = rawMarker.length > 0 ? rawMarker : defaults.marker;
+
+  const rawTimeout = Number(process.env.CCX_TIMEOUT || result.timeoutSeconds || defaults.timeoutSeconds);
+  result.timeoutSeconds = (isFinite(rawTimeout) && rawTimeout > 0) ? rawTimeout : defaults.timeoutSeconds;
+
+  return result;
+}
+
+/**
+ * Saves a partial config patch to disk.
+ * Creates directory if needed and merges with existing config.
+ */
+export function save(patch) {
+  const configFilePath = configPath();
+  const configDir = path.dirname(configFilePath);
+
+  // Create directory if it doesn't exist
+  fs.mkdirSync(configDir, { recursive: true });
+
+  // Read existing config or use empty object if file doesn't exist
+  let existing = {};
+  try {
+    if (fs.existsSync(configFilePath)) {
+      const fileContent = fs.readFileSync(configFilePath, 'utf8');
+      existing = JSON.parse(fileContent);
+    }
+  } catch (error) {
+    // If file doesn't exist or fails to parse, start with empty object
+  }
+
+  // Deep merge patch into existing
+  const merged = { ...existing, ...patch };
+
+  // Write pretty-printed JSON with 2-space indent
+  fs.writeFileSync(configFilePath, JSON.stringify(merged, null, 2) + '\n');
+}

package/src/gemini.js

@@ -0,0 +1,80 @@
+export class RateLimitError extends Error {}
+export class AuthError extends Error {}
+export class ModelError extends Error {}
+export class TimeoutError extends Error {}
+export class NetworkError extends Error {}
+
+const PROMPT_PREFIX =
+  'Rewrite the following text to be grammatically correct and clearer, ' +
+  'while preserving its original intent and meaning exactly. ' +
+  'This is a single line typed into a terminal prompt, not a chat message - ' +
+  'respond with EXACTLY ONE rewritten version as a single plain-text line. ' +
+  'Do not offer multiple options or alternatives. Do not add headings, bullet ' +
+  'points, markdown formatting, quotes, explanations, or any commentary. ' +
+  'Output must contain nothing but the rewritten line itself.\n\nText:\n';
+
+export async function enhance(text, config) {
+  const { geminiApiKey, geminiModel, timeoutSeconds } = config;
+
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${geminiModel}:generateContent`;
+  const controller = new AbortController();
+  let timeoutId;
+
+  try {
+    timeoutId = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      signal: controller.signal,
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': geminiApiKey,
+      },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: PROMPT_PREFIX + text }] }],
+      }),
+    });
+
+    // Handle bad HTTP status codes
+    if (!response.ok) {
+      const body = await response.text();
+      if (response.status === 429) {
+        throw new RateLimitError('Quota exceeded');
+      } else if (response.status === 401 || response.status === 403) {
+        throw new AuthError('Invalid key — run ccx init');
+      } else if (response.status === 404) {
+        throw new ModelError('Model not found — run ccx init');
+      } else {
+        const truncated = body.substring(0, 200);
+        throw new NetworkError(`API error ${response.status}: ${truncated}`);
+      }
+    }
+
+    // Parse response
+    const data = await response.json();
+    const result = data.candidates[0].content.parts.map(p => p.text || '').join('').trim();
+
+    if (!result) {
+      throw new NetworkError('Gemini returned empty response');
+    }
+
+    return result;
+  } catch (err) {
+    // Handle fetch errors
+    if (err.name === 'AbortError') {
+      throw new TimeoutError(`Timed out after ${timeoutSeconds}s`);
+    }
+
+    // Re-throw custom errors
+    if (err instanceof RateLimitError || err instanceof AuthError ||
+        err instanceof ModelError || err instanceof NetworkError ||
+        err instanceof TimeoutError) {
+      throw err;
+    }
+
+    // Wrap other errors as NetworkError
+    throw new NetworkError('No connection');
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/input.js

@@ -0,0 +1,128 @@
+/**
+ * src/input.js — pure stdin parser with Alt+M and ;; triggers
+ * No fetch, no stderr writes, no process.exit
+ */
+
+/**
+ * Parses ESC [ {digits/semicolons} _ sequences (win32-input-mode)
+ * Returns { consumed, vk, sc, uc, kd, cs, rc } or null
+ * @param {Buffer} chunk
+ * @param {number} i  - index of ESC byte
+ */
+function parseWin32InputSeq(chunk, i) {
+  if (chunk[i + 1] !== 0x5b) return null;
+  let j = i + 2;
+  const start = j;
+  while (j < chunk.length && ((chunk[j] >= 0x30 && chunk[j] <= 0x39) || chunk[j] === 0x3b)) j++;
+  if (j >= chunk.length || chunk[j] !== 0x5f || j === start) return null;
+  const parts = chunk.slice(start, j).toString('ascii').split(';').map(Number);
+  if (parts.length !== 6 || parts.some(Number.isNaN)) return null;
+  const [vk, sc, uc, kd, cs, rc] = parts;
+  return { consumed: j + 1 - i, vk, sc, uc, kd, cs, rc };
+}
+
+/**
+ * @param {{ marker: string, onEnhance: Function, onSubmit: Function, onPassthrough: Function, onCtrlC: Function }} opts
+ * @returns {{ processChunk(chunk: Buffer): void, setBusy(b: boolean): void, reset(): void }}
+ */
+export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough, onCtrlC }) {
+  let lineBuffer = '';
+  let busy = false;
+
+  function reset() {
+    lineBuffer = '';
+    busy = false;
+  }
+
+  function setBusy(b) {
+    busy = b;
+  }
+
+  function processChunk(chunk) {
+    // When busy, forward everything as-is
+    if (busy) {
+      onPassthrough(chunk);
+      return;
+    }
+
+    let i = 0;
+    while (i < chunk.length) {
+      const byte = chunk[i];
+
+      if (byte === 0x1b) {
+        // Try win32-input-mode sequence first
+        const seq = parseWin32InputSeq(chunk, i);
+        if (seq !== null) {
+          if (seq.kd === 1) {
+            if (seq.vk === 13) {
+              // Win32 Enter
+              if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
+                onEnhance(lineBuffer);
+                return;
+              } else {
+                onSubmit(lineBuffer);
+                lineBuffer = '';
+              }
+            } else if (seq.vk === 8) {
+              // Win32 Backspace
+              if (lineBuffer.length > 0) lineBuffer = lineBuffer.slice(0, -1);
+            } else if (seq.vk === 77 && (seq.cs & (0x0001 | 0x0002)) && !(seq.cs & (0x0004 | 0x0008))) {
+              // Win32 Alt+M
+              if (lineBuffer.length > 0) {
+                onEnhance(lineBuffer);
+                return;
+              }
+            }
+          }
+          onPassthrough(chunk.slice(i, i + seq.consumed));
+          i += seq.consumed;
+          continue;
+        }
+
+        // No win32 sequence — check for standard Alt+M (ESC followed by 0x6d)
+        if (i + 1 < chunk.length && chunk[i + 1] === 0x6d) {
+          if (lineBuffer.length > 0) {
+            onEnhance(lineBuffer);
+            return;
+          } else {
+            onPassthrough(chunk.slice(i, i + 2));
+            i += 2;
+          }
+        } else {
+          // Forward rest untouched
+          onPassthrough(chunk.slice(i));
+          return;
+        }
+      } else if (byte === 0x0d) {
+        // Enter
+        if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
+          onEnhance(lineBuffer);
+          return;
+        } else {
+          onSubmit(lineBuffer);
+          onPassthrough(Buffer.from([byte]));
+          lineBuffer = '';
+        }
+        i++;
+      } else if (byte === 0x03) {
+        // Ctrl+C
+        onCtrlC();
+        onPassthrough(Buffer.from([byte]));
+        lineBuffer = '';
+        i++;
+      } else if (byte === 0x7f || byte === 0x08) {
+        // Backspace
+        lineBuffer = lineBuffer.slice(0, -1);
+        onPassthrough(Buffer.from([byte]));
+        i++;
+      } else {
+        // Printable char
+        lineBuffer += String.fromCharCode(byte);
+        onPassthrough(Buffer.from([byte]));
+        i++;
+      }
+    }
+  }
+
+  return { processChunk, setBusy, reset };
+}

package/src/ui.js

@@ -0,0 +1,65 @@
+const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const FRAME_INTERVAL = 80; // ms
+
+let spinnerInterval = null;
+let currentFrame = 0;
+
+/**
+ * Draws the status line on stderr with cursor save/restore
+ */
+function drawStatusLine(content) {
+  const ansi = `\x1b[s\r\n\x1b[2K${content}\x1b[u`;
+  process.stderr.write(ansi);
+}
+
+/**
+ * Starts animating the Braille spinner on stderr
+ */
+export function start() {
+  // Reset frame counter and stop any existing interval
+  currentFrame = 0;
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+  }
+
+  spinnerInterval = setInterval(() => {
+    const frame = BRAILLE_FRAMES[currentFrame % BRAILLE_FRAMES.length];
+    drawStatusLine(`${frame} Enhancing prompt...`);
+    currentFrame++;
+  }, FRAME_INTERVAL);
+}
+
+/**
+ * Stops the spinner and shows a final status message
+ */
+export async function stop(state, message) {
+  // Clear the spinner interval
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+  }
+
+  // Draw final state based on success/error
+  const symbol = state === 'success' ? '✓' : '✗';
+  const colorCode = state === 'success' ? '32' : '31';
+  const statusLine = `\x1b[${colorCode}m${symbol} ${message}\x1b[0m`;
+
+  drawStatusLine(statusLine);
+
+  // Wait 400ms
+  await new Promise(r => setTimeout(r, 400));
+
+  // Clear the status line
+  drawStatusLine('');
+}
+
+/**
+ * Immediately clears the status line and stops spinner
+ */
+export function clear() {
+  if (spinnerInterval) {
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
+  }
+  drawStatusLine('');
+}