ccx-relay 1.5.0 → 1.6.0

package/bin/ccx-init.js

@@ -3,11 +3,10 @@
 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';
+import { enhance, listModels } 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);
@@ -37,23 +36,19 @@ async function promptHidden(question) {
   });
 }
 
-// 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}`);
@@ -61,30 +56,22 @@ function showConfig() {
   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.');
+    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);
-  }
+  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 });
@@ -94,49 +81,45 @@ async function runWizard() {
     process.exit(1);
   }
 
-  // Step 3: Model picker
-  const models = [
-    'gemini-2.5-flash',
-    'gemini-1.5-flash',
-    'gemini-2.5-pro'
-  ];
+  // Fetch available models, fall back to hardcoded list
+  let models;
+  process.stdout.write('  Fetching available models... ');
+  try {
+    const all = await listModels(key);
+    models = all.filter(m => m.includes('gemini')).slice(0, 10);
+    if (models.length === 0) throw new Error('empty');
+    console.log(`\x1b[32m✓\x1b[0m ${models.length} found`);
+  } catch (_) {
+    models = ['gemini-2.5-flash', 'gemini-1.5-flash', 'gemini-2.5-pro'];
+    console.log('(using defaults)');
+  }
 
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  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');
+  models.forEach((m, i) => {
+    console.log(`  ${i + 1}) ${m}${i === 0 ? ' (default)' : ''}`);
+  });
 
   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 idx = parseInt(modelChoice.trim(), 10);
+  const modelIndex = (!idx || idx < 1 || idx > models.length) ? 0 : idx - 1;
   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') {

package/bin/ccx.js

@@ -6,6 +6,49 @@ import { enhance, RateLimitError, AuthError, ModelError, TimeoutError, NetworkEr
 import { start as spinnerStart, stop as spinnerStop, clear as spinnerClear } from '../src/ui.js';
 import { createInputHandler } from '../src/input.js';
 
+const argv = process.argv.slice(2);
+
+// Shell tab-completion scripts
+if (argv[0] === 'completion') {
+  const shell = argv[1] || 'bash';
+  const scripts = {
+    bash: [
+      '_ccx_completion() {',
+      '    local cur="${COMP_WORDS[COMP_CWORD]}"',
+      '    COMPREPLY=($(compgen -W "claude bash zsh powershell cmd completion" -- "$cur"))',
+      '}',
+      'complete -F _ccx_completion ccx',
+    ].join('\n'),
+    zsh: [
+      '#compdef ccx',
+      '_ccx() {',
+      '    local -a cmds',
+      '    cmds=(claude bash zsh powershell cmd completion)',
+      '    _describe \'command\' cmds',
+      '}',
+      '_ccx',
+    ].join('\n'),
+    powershell: [
+      'Register-ArgumentCompleter -Native -CommandName ccx -ScriptBlock {',
+      '    param($wordToComplete, $commandAst, $cursorPosition)',
+      '    @(\'claude\',\'bash\',\'zsh\',\'powershell\',\'cmd\',\'completion\') | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {',
+      '        [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_)',
+      '    }',
+      '}',
+    ].join('\n'),
+  };
+  if (!scripts[shell]) {
+    process.stderr.write(`Unknown shell: ${shell}. Use: bash, zsh, powershell\n`);
+    process.exit(1);
+  }
+  process.stdout.write(scripts[shell] + '\n');
+  process.stdout.write('\n# To activate, add to your shell profile:\n');
+  if (shell === 'bash') process.stdout.write('# eval "$(ccx completion bash)"\n');
+  else if (shell === 'zsh') process.stdout.write('# eval "$(ccx completion zsh)"\n');
+  else if (shell === 'powershell') process.stdout.write('# Invoke-Expression (ccx completion powershell)\n');
+  process.exit(0);
+}
+
 let pty;
 try {
   pty = (await import('node-pty')).default;
@@ -21,7 +64,7 @@ try {
 const config = load();
 
 if (!config.geminiApiKey) {
-  process.stderr.write('[ccx] No API key found. Run `ccx init` to set up.\n');
+  process.stderr.write('[ccx] No API key found. Run `ccx-init` to set up.\n');
   process.exit(1);
 }
 
@@ -30,9 +73,8 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
   process.exit(1);
 }
 
-const argv      = process.argv.slice(2);
-const targetCmd = argv[0] || 'claude';
-const targetArgs= argv.slice(1);
+const targetCmd  = argv[0] || 'claude';
+const targetArgs = argv.slice(1);
 
 const isWindows = process.platform === 'win32';
 const shellFile = isWindows ? (process.env.COMSPEC || 'cmd.exe') : targetCmd;
@@ -46,7 +88,26 @@ const ptyProcess = pty.spawn(shellFile, shellArgs, {
   env:  process.env,
 });
 
-ptyProcess.onData(data => process.stdout.write(data));
+// Ring buffer of recent PTY output lines for context-aware enhancement
+const CONTEXT_MAX = 20;
+const contextLines = [];
+
+function stripAnsi(s) {
+  return s
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
+    .replace(/\x1b\][^\x07]*\x07/g, '')
+    .replace(/\r/g, '');
+}
+
+ptyProcess.onData(data => {
+  process.stdout.write(data);
+  for (const line of stripAnsi(data).split('\n')) {
+    if (line.trim()) {
+      contextLines.push(line.trim());
+      if (contextLines.length > CONTEXT_MAX) contextLines.shift();
+    }
+  }
+});
 
 process.stdout.on('resize', () => {
   ptyProcess.resize(process.stdout.columns, process.stdout.rows);
@@ -58,38 +119,42 @@ process.stdin.resume();
 const handler = createInputHandler({
   marker: config.marker,
 
-  onEnhance: async (line) => {
-    // line may include trailing marker (;;) for the ;; trigger — strip it
+  onEnhance: async (line, cursor) => {
     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);
+      const context = contextLines.length > 0 ? contextLines.join('\n') : null;
+      improved = await enhance(toSend, config, context);
     } 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 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
+      // Move cursor to end of line then erase, restore original
+      const charsAfterCursor = line.length - cursor;
+      if (charsAfterCursor > 0) ptyProcess.write(`\x1b[${charsAfterCursor}C`);
       ptyProcess.write(Buffer.alloc(line.length, 0x7f));
       ptyProcess.write(toSend);
       handler.setBusy(false);
+      handler.setLine(toSend);
       return;
     }
     await spinnerStop('success', 'Enhanced');
-    // Erase full echoed text (including marker), write improved
+    // Move cursor to end of line then erase, write improved
+    const charsAfterCursor = line.length - cursor;
+    if (charsAfterCursor > 0) ptyProcess.write(`\x1b[${charsAfterCursor}C`);
     ptyProcess.write(Buffer.alloc(line.length, 0x7f));
     ptyProcess.write(improved);
     handler.setBusy(false);
+    handler.setLine(improved);
   },
 
-  onSubmit: (_line) => {
-    // Enter already forwarded by input.js passthrough
-  },
+  onSubmit: (_line) => {},
 
   onPassthrough: (chunk) => ptyProcess.write(chunk),
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "ccx-relay",
-  "version": "1.5.0",
+  "version": "1.6.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": {

package/src/gemini.js

@@ -4,75 +4,82 @@ export class ModelError extends Error {}
 export class TimeoutError extends Error {}
 export class NetworkError extends Error {}
 
-const PROMPT_PREFIX =
+const SYSTEM_PROMPT =
   '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';
+  'Output must contain nothing but the rewritten line itself.';
 
-export async function enhance(text, config) {
-  const { geminiApiKey, geminiModel, timeoutSeconds } = config;
+function buildAuthHeaders(apiKey) {
+  return apiKey.startsWith('AQ.')
+    ? { 'Authorization': `Bearer ${apiKey}` }
+    : { 'x-goog-api-key': apiKey };
+}
+
+export async function listModels(apiKey) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 10000);
+  try {
+    const response = await fetch(
+      'https://generativelanguage.googleapis.com/v1beta/models',
+      {
+        headers: { 'Content-Type': 'application/json', ...buildAuthHeaders(apiKey) },
+        signal: controller.signal,
+      }
+    );
+    if (!response.ok) throw new AuthError('Could not fetch model list');
+    const data = await response.json();
+    return (data.models || [])
+      .filter(m => m.supportedGenerationMethods?.includes('generateContent'))
+      .map(m => m.name.replace('models/', ''));
+  } catch (err) {
+    if (err instanceof AuthError) throw err;
+    throw new NetworkError('Could not fetch model list');
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
 
+export async function enhance(text, config, context = null) {
+  const { geminiApiKey, geminiModel, timeoutSeconds } = config;
   const url = `https://generativelanguage.googleapis.com/v1beta/models/${geminiModel}:generateContent`;
   const controller = new AbortController();
   let timeoutId;
 
+  const promptText = context
+    ? `${SYSTEM_PROMPT}\n\nRecent terminal context:\n${context}\n\nText:\n${text}`
+    : `${SYSTEM_PROMPT}\n\nText:\n${text}`;
+
   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 }] }],
-      }),
+      headers: { 'Content-Type': 'application/json', ...buildAuthHeaders(geminiApiKey) },
+      body: JSON.stringify({ contents: [{ parts: [{ text: promptText }] }] }),
     });
 
-    // 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}`);
-      }
+      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 throw new NetworkError(`API error ${response.status}: ${body.substring(0, 200)}`);
     }
 
-    // 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');
-    }
-
+    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.name === 'AbortError') throw new TimeoutError(`Timed out after ${timeoutSeconds}s`);
     if (err instanceof RateLimitError || err instanceof AuthError ||
         err instanceof ModelError || err instanceof NetworkError ||
-        err instanceof TimeoutError) {
-      throw err;
-    }
-
-    // Wrap other errors as NetworkError
+        err instanceof TimeoutError) throw err;
     throw new NetworkError('No connection');
   } finally {
     clearTimeout(timeoutId);

package/src/input.js

@@ -1,14 +1,3 @@
-/**
- * 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;
@@ -21,16 +10,25 @@ function parseWin32InputSeq(chunk, i) {
   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 }}
- */
+// Parses standard CSI sequences: ESC [ params final
+function parseCsiSeq(chunk, i) {
+  if (i + 1 >= chunk.length || chunk[i + 1] !== 0x5b) return null;
+  let j = i + 2;
+  while (j < chunk.length && chunk[j] >= 0x20 && chunk[j] <= 0x3f) j++;
+  if (j >= chunk.length || chunk[j] < 0x40 || chunk[j] > 0x7e) return null;
+  const params = chunk.slice(i + 2, j).toString('ascii');
+  const final = String.fromCharCode(chunk[j]);
+  return { consumed: j + 1 - i, params, final };
+}
+
 export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough, onCtrlC }) {
   let lineBuffer = '';
+  let cursor = 0;
   let busy = false;
 
   function reset() {
     lineBuffer = '';
+    cursor = 0;
     busy = false;
   }
 
@@ -38,40 +36,48 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
     busy = b;
   }
 
+  // Sync internal buffer after external rewrite (e.g. after enhancement)
+  function setLine(str) {
+    lineBuffer = str;
+    cursor = str.length;
+  }
+
   function processChunk(chunk) {
-    // When busy, forward everything as-is
-    if (busy) {
-      onPassthrough(chunk);
-      return;
-    }
+    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
+        // 1. Win32 input mode sequence
         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);
+                onEnhance(lineBuffer, cursor);
                 return;
               } else {
                 onSubmit(lineBuffer);
                 lineBuffer = '';
+                cursor = 0;
               }
             } 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;
+              if (cursor > 0) {
+                lineBuffer = lineBuffer.slice(0, cursor - 1) + lineBuffer.slice(cursor);
+                cursor--;
               }
+            } else if (seq.vk === 37) {
+              cursor = Math.max(0, cursor - 1);
+            } else if (seq.vk === 39) {
+              cursor = Math.min(lineBuffer.length, cursor + 1);
+            } else if (seq.vk === 36) {
+              cursor = 0;
+            } else if (seq.vk === 35) {
+              cursor = lineBuffer.length;
+            } else if (seq.vk === 77 && (seq.cs & (0x0001 | 0x0002)) && !(seq.cs & (0x0004 | 0x0008))) {
+              if (lineBuffer.length > 0) { onEnhance(lineBuffer, cursor); return; }
             }
           }
           onPassthrough(chunk.slice(i, i + seq.consumed));
@@ -79,50 +85,67 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
           continue;
         }
 
-        // No win32 sequence — check for standard Alt+M (ESC followed by 0x6d)
+        // 2. Alt+M (ESC m)
         if (i + 1 < chunk.length && chunk[i + 1] === 0x6d) {
           if (lineBuffer.length > 0) {
-            onEnhance(lineBuffer);
+            onEnhance(lineBuffer, cursor);
             return;
           } else {
             onPassthrough(chunk.slice(i, i + 2));
             i += 2;
           }
-        } else {
-          // Forward rest untouched
-          onPassthrough(chunk.slice(i));
-          return;
+          continue;
         }
+
+        // 3. Standard CSI sequences (arrows, Home, End, etc.)
+        const csi = parseCsiSeq(chunk, i);
+        if (csi !== null) {
+          if      (csi.final === 'D' && !csi.params) cursor = Math.max(0, cursor - 1);
+          else if (csi.final === 'C' && !csi.params) cursor = Math.min(lineBuffer.length, cursor + 1);
+          else if (csi.final === 'H' && !csi.params) cursor = 0;
+          else if (csi.final === 'F' && !csi.params) cursor = lineBuffer.length;
+          else if (csi.final === '~' && csi.params === '1') cursor = 0;
+          else if (csi.final === '~' && csi.params === '4') cursor = lineBuffer.length;
+          onPassthrough(chunk.slice(i, i + csi.consumed));
+          i += csi.consumed;
+          continue;
+        }
+
+        // 4. Unknown ESC sequence — forward rest of chunk
+        onPassthrough(chunk.slice(i));
+        return;
       } else if (byte === 0x0d) {
-        // Enter
         if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
-          onEnhance(lineBuffer);
+          onEnhance(lineBuffer, cursor);
           return;
         } else {
           onSubmit(lineBuffer);
           onPassthrough(Buffer.from([byte]));
           lineBuffer = '';
+          cursor = 0;
         }
         i++;
       } else if (byte === 0x03) {
-        // Ctrl+C
         onCtrlC();
         onPassthrough(Buffer.from([byte]));
         lineBuffer = '';
+        cursor = 0;
         i++;
       } else if (byte === 0x7f || byte === 0x08) {
-        // Backspace
-        lineBuffer = lineBuffer.slice(0, -1);
+        if (cursor > 0) {
+          lineBuffer = lineBuffer.slice(0, cursor - 1) + lineBuffer.slice(cursor);
+          cursor--;
+        }
         onPassthrough(Buffer.from([byte]));
         i++;
       } else {
-        // Printable char
-        lineBuffer += String.fromCharCode(byte);
+        lineBuffer = lineBuffer.slice(0, cursor) + String.fromCharCode(byte) + lineBuffer.slice(cursor);
+        cursor++;
         onPassthrough(Buffer.from([byte]));
         i++;
       }
     }
   }
 
-  return { processChunk, setBusy, reset };
+  return { processChunk, setBusy, reset, setLine };
 }

package/src/ui.js

@@ -1,27 +1,17 @@
 const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const FRAME_INTERVAL = 80; // ms
+const FRAME_INTERVAL = 80;
 
 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);
+  const row = process.stdout.rows || 24;
+  process.stderr.write(`\x1b[s\x1b[${row};1H\x1b[2K${content}\x1b[u`);
 }
 
-/**
- * Starts animating the Braille spinner on stderr
- */
 export function start() {
-  // Reset frame counter and stop any existing interval
   currentFrame = 0;
-  if (spinnerInterval) {
-    clearInterval(spinnerInterval);
-  }
-
+  if (spinnerInterval) clearInterval(spinnerInterval);
   spinnerInterval = setInterval(() => {
     const frame = BRAILLE_FRAMES[currentFrame % BRAILLE_FRAMES.length];
     drawStatusLine(`${frame} Enhancing prompt...`);
@@ -29,37 +19,16 @@ export function start() {
   }, 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
+  if (spinnerInterval) { clearInterval(spinnerInterval); spinnerInterval = null; }
   const symbol = state === 'success' ? '✓' : '✗';
   const colorCode = state === 'success' ? '32' : '31';
-  const statusLine = `\x1b[${colorCode}m${symbol} ${message}\x1b[0m`;
-
-  drawStatusLine(statusLine);
-
-  // Wait 400ms
+  drawStatusLine(`\x1b[${colorCode}m${symbol} ${message}\x1b[0m`);
   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;
-  }
+  if (spinnerInterval) { clearInterval(spinnerInterval); spinnerInterval = null; }
   drawStatusLine('');
 }