@compilr-dev/cli 0.6.2 → 0.6.4

package/dist/commands-v2/handlers/core.js

@@ -171,8 +171,8 @@ export const menuCommand = {
             console.log(s.muted('    Run: npm update -g @compilr-dev/cli'));
             console.log('');
         }
-        // Dashboard loop - returns to dashboard after sub-commands until user exits or continues
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        // Dashboard loop — returns to dashboard after sub-commands until user exits or continues
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop; exit happens via internal break/return
         while (true) {
             const dashboard = new DashboardOverlayV2();
             const result = await ctx.ui.showOverlay(dashboard);

package/dist/commands-v2/handlers/index.d.ts

@@ -22,4 +22,5 @@ export * from './terminals.js';
 export * from './notifications.js';
 export * from './mcp.js';
 export * from './delegations.js';
+export * from './perf.js';
 export declare const allCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/index.js

@@ -21,6 +21,7 @@ import { terminalsCommands } from './terminals.js';
 import { notificationsCommands } from './notifications.js';
 import { mcpCommands } from './mcp.js';
 import { delegationsCommands } from './delegations.js';
+import { perfCommands } from './perf.js';
 // Re-export individual modules
 export * from './core.js';
 export * from './settings.js';
@@ -40,6 +41,7 @@ export * from './terminals.js';
 export * from './notifications.js';
 export * from './mcp.js';
 export * from './delegations.js';
+export * from './perf.js';
 // All commands combined
 export const allCommands = [
     ...coreCommands,
@@ -60,4 +62,5 @@ export const allCommands = [
     ...notificationsCommands,
     ...mcpCommands,
     ...delegationsCommands,
+    ...perfCommands,
 ];

package/dist/commands-v2/handlers/perf.d.ts

@@ -0,0 +1,9 @@
+/**
+ * /perf Command
+ *
+ * Display the most recent CLI startup-performance profile.
+ * The profile is captured automatically and written to
+ * ~/.compilr-dev/startup-perf.log on every launch.
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const perfCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/perf.js

@@ -0,0 +1,66 @@
+/**
+ * /perf Command
+ *
+ * Display the most recent CLI startup-performance profile.
+ * The profile is captured automatically and written to
+ * ~/.compilr-dev/startup-perf.log on every launch.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import pc from 'picocolors';
+import { getDataPath } from '../../settings/paths.js';
+const perfCommand = {
+    name: 'perf',
+    description: 'Show the latest startup-performance profile',
+    details: 'Display the timing breakdown captured during this CLI launch. ' +
+        'Useful for diagnosing slow startups (cold cache, heavy MCP servers, ' +
+        'large project DBs). The profile is overwritten on every launch.',
+    examples: [{ code: '/perf', description: 'Show the most recent startup profile' }],
+    execute(_args, ctx) {
+        const logPath = path.join(getDataPath(), 'startup-perf.log');
+        if (!fs.existsSync(logPath)) {
+            ctx.ui.print({
+                type: 'info',
+                message: 'No startup profile found. (Profile is written on the next launch.)',
+            });
+            return Promise.resolve(true);
+        }
+        let content;
+        try {
+            content = fs.readFileSync(logPath, 'utf-8');
+        }
+        catch (err) {
+            ctx.ui.print({
+                type: 'warning',
+                message: `Could not read startup profile: ${String(err)}`,
+            });
+            return Promise.resolve(true);
+        }
+        if (!content.trim()) {
+            ctx.ui.print({ type: 'info', message: 'Startup profile is empty.' });
+            return Promise.resolve(true);
+        }
+        // Print the profile, dimming the path footer.
+        const lines = content.split('\n');
+        const out = [];
+        for (const line of lines) {
+            if (line.startsWith('===')) {
+                out.push(pc.bold(line));
+            }
+            else if (line.startsWith('Slow steps')) {
+                out.push(pc.yellow(line));
+            }
+            else if (line.startsWith('Total:')) {
+                out.push(pc.cyan(line));
+            }
+            else {
+                out.push(line);
+            }
+        }
+        out.push('');
+        out.push(pc.dim(`  Profile: ${logPath}`));
+        ctx.ui.print({ type: 'raw-lines', lines: out });
+        return Promise.resolve(true);
+    },
+};
+export const perfCommands = [perfCommand];

package/dist/commands-v2/handlers/project.js

@@ -178,9 +178,8 @@ export const initCommand = {
         'Type to enter values in input steps',
     ],
     async execute(_args, ctx) {
-        // Show onboarding wizard (same as first-run experience)
-        // Loop if user chooses to configure keys
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        // Show onboarding wizard (same as first-run experience).
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop; exit happens via internal break/return
         while (true) {
             const wizard = new OnboardingWizardOverlayV2();
             const result = await ctx.ui.showOverlay(wizard);

package/dist/index.js

@@ -88,7 +88,7 @@ function showHelp() {
     console.log(`
 @compilr-dev/cli v${VERSION}
 
-Usage: npm run dev [options]
+Usage: compilr [options]
 
 Options:
   --provider, -p <provider>   LLM provider (claude, openai, gemini, ollama)
@@ -103,13 +103,16 @@ Environment Variables:
   ANTHROPIC_API_KEY           Required for Claude provider
   OPENAI_API_KEY              Required for OpenAI provider
   GOOGLE_AI_API_KEY           Required for Gemini provider
+  NO_COLOR                    Disable ANSI colors
+  COMPILR_NO_UPDATE_CHECK     Skip the npm registry update check at startup
+  CI                          Auto-skips the update check
 
 Examples:
-  npm run dev
-  npm run dev -- --model claude-sonnet-4-6
-  npm run dev -- --provider gemini --model gemini-2.0-flash
-  npm run dev -- --minimal --show-filtering
-  npm run dev -- --update
+  compilr
+  compilr --model claude-sonnet-4-6
+  compilr --provider gemini --model gemini-2.0-flash
+  compilr --minimal --show-filtering
+  compilr --update
 `);
 }
 // =============================================================================

package/dist/repl-v2.js

@@ -3306,28 +3306,34 @@ export class ReplV2 {
             tokenDisplay += ` (${extras.join(', ')})`;
         }
         parts.push(tokenDisplay);
-        // Add token breakdown
+        // Detailed breakdown is logged (not printed) to keep the per-turn
+        // footer focused on duration + tokens. Set COMPILR_VERBOSE_FOOTER=1
+        // to bring back the inline breakdown for debugging.
         const cacheInfo = formatCacheInfo();
-        if (cacheInfo) {
-            // Show cache info if available
-            parts.push(cacheInfo);
-        }
-        else {
-            // Show component breakdown
-            const breakdown = formatBreakdownCompact();
-            if (breakdown) {
+        const breakdown = cacheInfo ?? formatBreakdownCompact();
+        log.debug({
+            component: 'turn-summary',
+            durationMs: metrics.durationMs,
+            inputTokens: metrics.inputTokens,
+            outputTokens: metrics.outputTokens,
+            thinkingTokens: metrics.thinkingTokens,
+            cacheReadTokens: metrics.cacheReadTokens,
+            toolCalls: metrics.toolCalls,
+            apiCalls: metrics.apiCalls,
+            breakdown,
+            debugPayload: metrics.debugPayload,
+        }, 'Turn summary');
+        if (process.env.COMPILR_VERBOSE_FOOTER === '1') {
+            if (breakdown)
                 parts.push(breakdown);
+            if (metrics.toolCalls > 0) {
+                parts.push(`${String(metrics.toolCalls)} tool${metrics.toolCalls > 1 ? 's' : ''}`);
+            }
+            if (metrics.debugPayload) {
+                const { systemTokens, contentsTokens, toolsTokens } = metrics.debugPayload;
+                const totalTokens = systemTokens + contentsTokens + toolsTokens;
+                parts.push(`[dbg ${String(metrics.apiCalls)}calls sent:${formatTokens(totalTokens)} sys:${formatTokens(systemTokens)} cont:${formatTokens(contentsTokens)} tools:${formatTokens(toolsTokens)}]`);
             }
-        }
-        if (metrics.toolCalls > 0) {
-            parts.push(`${String(metrics.toolCalls)} tool${metrics.toolCalls > 1 ? 's' : ''}`);
-        }
-        // DEBUG: Show payload debug info (token estimates sent to provider)
-        if (metrics.debugPayload) {
-            const { systemTokens, contentsTokens, toolsTokens } = metrics.debugPayload;
-            const totalTokens = systemTokens + contentsTokens + toolsTokens;
-            // Format: [dbg 2calls sent:31k sys:10k cont:8k tools:13k]
-            parts.push(`[dbg ${String(metrics.apiCalls)}calls sent:${formatTokens(totalTokens)} sys:${formatTokens(systemTokens)} cont:${formatTokens(contentsTokens)} tools:${formatTokens(toolsTokens)}]`);
         }
         // Print as muted info line
         this.ui.print({ type: 'turn-summary', parts });
@@ -3358,8 +3364,12 @@ export class ReplV2 {
 // Only run main() when executed directly (not when imported)
 if (import.meta.url === `file://${process.argv[1]}`) {
     const repl = new ReplV2();
-    // Handle SIGINT
+    // Handle SIGINT — restore raw mode before exit so the parent shell
+    // doesn't inherit a broken terminal state.
     process.on('SIGINT', () => {
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
         console.log('\n\nInterrupted\n');
         process.exit(0);
     });

package/dist/session/project-session-manager.js

@@ -387,7 +387,7 @@ export class ProjectSessionManager {
             else if (Array.isArray(lastUserMsg.content)) {
                 const textBlock = lastUserMsg.content.find((b) => b.type === 'text');
                 if (textBlock?.type === 'text') {
-                    preview = textBlock.text;
+                    preview = (textBlock).text;
                 }
             }
         }

package/dist/slash-autocomplete.js

@@ -9,6 +9,7 @@
  * - Proper wrapping for long input
  */
 import pc from 'picocolors';
+import { ttyWrite } from './ui/terminal.js';
 // ANSI escape codes for terminal control
 const ANSI = {
     HIDE_CURSOR: '\x1B[?25l',
@@ -83,7 +84,7 @@ function renderDropdown(state, promptLen, currentLine, totalLines, hasSeparators
     if (hasSeparators)
         linesToMoveDown += 1;
     if (linesToMoveDown > 0) {
-        process.stdout.write(ANSI.MOVE_DOWN(linesToMoveDown));
+        ttyWrite(ANSI.MOVE_DOWN(linesToMoveDown));
     }
     process.stdout.write('\n');
     const visible = state.matches.slice(0, MAX_VISIBLE);
@@ -98,8 +99,8 @@ function renderDropdown(state, promptLen, currentLine, totalLines, hasSeparators
     // Move back up to cursor position
     const linesRendered = visible.length;
     const linesToMoveUp = linesRendered + linesToMoveDown + 1;
-    process.stdout.write(ANSI.MOVE_UP(linesToMoveUp));
-    process.stdout.write(ANSI.MOVE_TO_COLUMN(promptLen + state.cursorPos + 1));
+    ttyWrite(ANSI.MOVE_UP(linesToMoveUp));
+    ttyWrite(ANSI.MOVE_TO_COLUMN(promptLen + state.cursorPos + 1));
     return linesRendered;
 }
 /**
@@ -113,16 +114,17 @@ function clearDropdown(dropdownLines, currentLine, totalLines, hasSeparators) {
     if (hasSeparators)
         linesToMoveDown += 1;
     if (linesToMoveDown > 0) {
-        process.stdout.write(ANSI.MOVE_DOWN(linesToMoveDown));
+        ttyWrite(ANSI.MOVE_DOWN(linesToMoveDown));
     }
     process.stdout.write('\n');
     // Clear dropdown lines
     for (let i = 0; i < dropdownLines; i++) {
-        process.stdout.write(ANSI.CLEAR_LINE + '\n');
+        ttyWrite(ANSI.CLEAR_LINE);
+        process.stdout.write('\n');
     }
     // Move back up
     const linesToMoveUp = dropdownLines + linesToMoveDown + 1;
-    process.stdout.write(ANSI.MOVE_UP(linesToMoveUp));
+    ttyWrite(ANSI.MOVE_UP(linesToMoveUp));
 }
 /**
  * Create interactive input with autocomplete
@@ -198,13 +200,13 @@ export function createInteractiveInput(prompt, onSubmit, showSeparator = true, g
         const termWidth = getTerminalWidth();
         // Clear previous render
         if (linesAboveCursor > 0) {
-            process.stdout.write('\r');
-            process.stdout.write(ANSI.MOVE_UP(linesAboveCursor));
+            ttyWrite('\r');
+            ttyWrite(ANSI.MOVE_UP(linesAboveCursor));
         }
         else {
-            process.stdout.write('\r');
+            ttyWrite('\r');
         }
-        process.stdout.write(ANSI.CLEAR_TO_END_OF_SCREEN);
+        ttyWrite(ANSI.CLEAR_TO_END_OF_SCREEN);
         // Render todos
         renderedTodoLines = renderTodoSection();
         // Render top separator
@@ -246,10 +248,10 @@ export function createInteractiveInput(prompt, onSubmit, showSeparator = true, g
         }
         linesToMoveUp += (currentLinePhysical - 1 - cursorPhysicalRow);
         if (linesToMoveUp > 0) {
-            process.stdout.write(ANSI.MOVE_UP(linesToMoveUp));
+            ttyWrite(ANSI.MOVE_UP(linesToMoveUp));
         }
         const cursorCol = (cursorAbsPos % termWidth) + 1;
-        process.stdout.write(ANSI.MOVE_TO_COLUMN(cursorCol));
+        ttyWrite(ANSI.MOVE_TO_COLUMN(cursorCol));
         // Track cursor position for next render
         linesAboveCursor = physicalLinesRendered + physicalLinesBeforeCursor + cursorPhysicalRow;
     }
@@ -339,9 +341,9 @@ export function createInteractiveInput(prompt, onSubmit, showSeparator = true, g
             dropdownLines = 0;
             // Clear display
             if (linesAboveCursor > 0) {
-                process.stdout.write('\r' + ANSI.MOVE_UP(linesAboveCursor));
+                ttyWrite('\r' + ANSI.MOVE_UP(linesAboveCursor));
             }
-            process.stdout.write('\r' + ANSI.CLEAR_TO_END_OF_SCREEN);
+            ttyWrite('\r' + ANSI.CLEAR_TO_END_OF_SCREEN);
             // Print clean input
             for (let i = 0; i < state.lines.length; i++) {
                 const linePrompt = i === 0 ? prompt : pc.dim('   \\ ');
@@ -494,7 +496,7 @@ export function createInteractiveInput(prompt, onSubmit, showSeparator = true, g
         if (isLeftArrow) {
             if (state.cursorPos > 0) {
                 state.cursorPos--;
-                process.stdout.write('\x1B[D');
+                ttyWrite('\x1B[D');
             }
             else if (state.currentLine > 0) {
                 state.currentLine--;
@@ -507,7 +509,7 @@ export function createInteractiveInput(prompt, onSubmit, showSeparator = true, g
         if (isRightArrow) {
             if (state.cursorPos < state.lines[state.currentLine].length) {
                 state.cursorPos++;
-                process.stdout.write('\x1B[C');
+                ttyWrite('\x1B[C');
             }
             else if (state.currentLine < state.lines.length - 1) {
                 state.currentLine++;

package/dist/tabbed-menu.js

@@ -7,6 +7,7 @@
 import pc from 'picocolors';
 import { getCustomCommandRegistry } from './commands/index.js';
 import { truncate } from './ui/base/index.js';
+import { ttyWrite } from './ui/terminal.js';
 // ANSI escape codes
 const ANSI = {
     HIDE_CURSOR: '\x1B[?25l',
@@ -201,11 +202,11 @@ function render(state, prevLineCount) {
     // Clear previous render
     if (prevLineCount > 0) {
         // Move to column 1, move up to first line, clear everything below
-        process.stdout.write('\r');
+        ttyWrite('\r');
         if (prevLineCount > 1) {
-            process.stdout.write(ANSI.MOVE_UP(prevLineCount - 1));
+            ttyWrite(ANSI.MOVE_UP(prevLineCount - 1));
         }
-        process.stdout.write(ANSI.CLEAR_TO_END);
+        ttyWrite(ANSI.CLEAR_TO_END);
     }
     // Render new content
     process.stdout.write(lines.join('\n'));
@@ -283,7 +284,7 @@ export function showHelpMenu() {
         // Start on a new line (menu appears below the prompt)
         process.stdout.write('\n');
         // Hide cursor during menu display
-        process.stdout.write(ANSI.HIDE_CURSOR);
+        ttyWrite(ANSI.HIDE_CURSOR);
         // Store original raw mode state
         const wasRawMode = process.stdin.isRaw;
         // Enable raw mode
@@ -298,13 +299,13 @@ export function showHelpMenu() {
             // lineCount lines with lineCount-1 newlines between them, plus the initial \n we added
             // So cursor is (lineCount-1)+1 = lineCount lines below where "You: /help" ended
             if (lineCount > 0) {
-                process.stdout.write(ANSI.MOVE_UP(lineCount));
-                process.stdout.write(ANSI.CLEAR_TO_END);
+                ttyWrite(ANSI.MOVE_UP(lineCount));
+                ttyWrite(ANSI.CLEAR_TO_END);
             }
             // Print newline so next prompt appears on fresh line
             process.stdout.write('\n');
             // Show cursor
-            process.stdout.write(ANSI.SHOW_CURSOR);
+            ttyWrite(ANSI.SHOW_CURSOR);
             // Restore raw mode to original state
             if (process.stdin.isTTY && !wasRawMode) {
                 process.stdin.setRawMode(false);

package/dist/ui/base/overlay-base.js

@@ -42,6 +42,7 @@ import * as terminal from '../terminal.js';
 import { getStyles } from '../../themes/index.js';
 import { OverlayLifecycle } from './overlay-lifecycle.js';
 import { debugLog } from '../../utils/debug-log.js';
+import { ttyWrite } from '../terminal.js';
 // =============================================================================
 // BaseOverlay Abstract Class
 // =============================================================================
@@ -150,7 +151,7 @@ export class BaseOverlay {
         this.state.maxLineCount = 0;
         // Explicitly move cursor to home and save position
         // This ensures we're at (0,0) regardless of what clearScreen() did
-        process.stdout.write('\x1b[H');
+        ttyWrite('\x1b[H');
         terminal.saveCursor();
     }
     // ===========================================================================

package/dist/ui/overlay/impl/artifact-detail-overlay-v2.js

@@ -14,6 +14,7 @@ import { markedTerminal } from 'marked-terminal';
 import { BaseOverlayV2 } from '../../base/overlay-base-v2.js';
 import { getCurrentTheme } from '../../../themes/index.js';
 import * as terminal from '../../terminal.js';
+import { ttyWrite } from '../../terminal.js';
 import { ARTIFACT_TYPE_LABELS } from '../../constants/labels.js';
 // =============================================================================
 // Alternate Screen Buffer Management
@@ -22,14 +23,14 @@ let inAlternateScreen = false;
 function enterAlternateScreen() {
     if (inAlternateScreen)
         return;
-    process.stdout.write('\x1b[?1049h'); // Switch to alternate screen
-    process.stdout.write('\x1b[H'); // Move cursor to home
+    ttyWrite('\x1b[?1049h'); // Switch to alternate screen
+    ttyWrite('\x1b[H'); // Move cursor to home
     inAlternateScreen = true;
 }
 function exitAlternateScreen() {
     if (!inAlternateScreen)
         return;
-    process.stdout.write('\x1b[?1049l'); // Switch back to main screen
+    ttyWrite('\x1b[?1049l'); // Switch back to main screen
     inAlternateScreen = false;
 }
 // Ensure we exit alternate screen on process termination
@@ -42,10 +43,14 @@ function setupAlternateScreenCleanup() {
         cleanup();
         process.exit(130);
     });
-    process.on('SIGTERM', () => {
-        cleanup();
-        process.exit(143);
-    });
+    // Windows doesn't deliver SIGTERM — Node silently ignores the listener
+    // there, but we add the platform guard for clarity.
+    if (process.platform !== 'win32') {
+        process.on('SIGTERM', () => {
+            cleanup();
+            process.exit(143);
+        });
+    }
 }
 setupAlternateScreenCleanup();
 // =============================================================================

package/dist/ui/overlay/impl/config-overlay-v2.js

@@ -611,9 +611,9 @@ export class ConfigOverlayV2 extends BaseOverlayV2 {
      */
     toggleOrCycleItem() {
         const item = this.state.configItems[this.state.selectedItem];
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- selectedItem can briefly point past array end during async re-render
         if (!item)
-            return null; // Defensive check
+            return null;
         if (item.type === 'boolean') {
             const newValue = !item.value;
             item.value = newValue;

package/dist/ui/overlay/impl/document-detail-overlay-v2.js

@@ -13,6 +13,7 @@
  */
 import chalk from 'chalk';
 import hljs from 'highlight.js';
+import { ttyWrite } from '../../terminal.js';
 // =============================================================================
 // Alternate Screen Buffer Management
 // =============================================================================
@@ -20,14 +21,14 @@ let inAlternateScreen = false;
 function enterAlternateScreen() {
     if (inAlternateScreen)
         return;
-    process.stdout.write('\x1b[?1049h'); // Switch to alternate screen
-    process.stdout.write('\x1b[H'); // Move cursor to home
+    ttyWrite('\x1b[?1049h'); // Switch to alternate screen
+    ttyWrite('\x1b[H'); // Move cursor to home
     inAlternateScreen = true;
 }
 function exitAlternateScreen() {
     if (!inAlternateScreen)
         return;
-    process.stdout.write('\x1b[?1049l'); // Switch back to main screen
+    ttyWrite('\x1b[?1049l'); // Switch back to main screen
     inAlternateScreen = false;
 }
 // Ensure we exit alternate screen on process termination
@@ -42,11 +43,14 @@ function setupAlternateScreenCleanup() {
         cleanup();
         process.exit(130);
     });
-    // Handle termination
-    process.on('SIGTERM', () => {
-        cleanup();
-        process.exit(143);
-    });
+    // Handle termination (Windows doesn't deliver SIGTERM — Node silently
+    // ignores the listener there, but we add the platform guard for clarity)
+    if (process.platform !== 'win32') {
+        process.on('SIGTERM', () => {
+            cleanup();
+            process.exit(143);
+        });
+    }
     // Handle uncaught exceptions
     process.on('uncaughtException', (err) => {
         cleanup();

package/dist/ui/overlay/impl/pending-overlay-v2.js

@@ -203,7 +203,10 @@ export class PendingOverlayV2 extends BaseOverlayV2 {
         const agentLabel = `$${req.agentId}`;
         const ctx = req.context;
         const filePath = ctx?.input
-            ? (ctx.input.filePath ?? ctx.input.file_path ?? ctx.input.path ?? '')
+            ? (() => {
+                const input = ctx.input;
+                return (input.filePath ?? input.file_path ?? input.path ?? '');
+            })()
             : '';
         const fileName = filePath.split('/').pop() || filePath;
         // Header

package/dist/ui/overlay-manager.js

@@ -6,6 +6,7 @@
  * clear/render and console output.
  */
 import * as terminal from './terminal.js';
+import { ttyWrite } from './terminal.js';
 import { getVisibleLength } from './line-utils.js';
 import { getStyles } from '../themes/index.js';
 export class OverlayManager {
@@ -89,7 +90,7 @@ export class OverlayManager {
     // ===========================================================================
     enterFullscreenOverlayMode() {
         this.host.clearFooter();
-        process.stdout.write('\x1b[2J\x1b[H');
+        ttyWrite('\x1b[2J\x1b[H');
         this.renderState = { lineCount: 0, maxLineCount: 0 };
     }
     enterInlineOverlayMode() {
@@ -127,9 +128,9 @@ export class OverlayManager {
     clearOverlayRender() {
         const linesToClear = this.renderState.maxLineCount;
         if (linesToClear > 0) {
-            process.stdout.write(`\x1b[${String(linesToClear)}A`);
-            process.stdout.write('\r');
-            process.stdout.write('\x1b[J');
+            ttyWrite(`\x1b[${String(linesToClear)}A`);
+            ttyWrite('\r');
+            ttyWrite('\x1b[J');
         }
     }
     renderOverlay() {
@@ -179,9 +180,9 @@ export class OverlayManager {
             const { line, column } = content.cursorPosition;
             const linesFromEnd = paddedLines.length - 1 - line;
             if (linesFromEnd > 0) {
-                process.stdout.write(`\x1b[${String(linesFromEnd)}A`);
+                ttyWrite(`\x1b[${String(linesFromEnd)}A`);
             }
-            process.stdout.write(`\x1b[${String(column)}G`);
+            ttyWrite(`\x1b[${String(column)}G`);
         }
         terminal.showCursor();
     }

package/dist/ui/terminal-render-item.js

@@ -229,7 +229,8 @@ export function renderItem(item, config) {
                 // If we add items that don't add trailing blanks, or if the rendering
                 // order changes, this could cause visual artifacts (overwriting content).
                 // If issues arise, consider tracking the last printed item type instead.
-                process.stdout.write('\x1b[1A'); // Move up one line
+                if (process.stdout.isTTY)
+                    process.stdout.write('\x1b[1A'); // Move up one line
             }
             // Show interrupted line with mascot
             const suggestion = item.suggestion ?? 'What should I do instead?';

package/dist/ui/terminal-renderer.js

@@ -407,8 +407,7 @@ export class TerminalRenderer extends EventEmitter {
         finally {
             this.isRendering = false;
             // Check if another render was requested during this one
-            // (renderPending can be set by callbacks during render)
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- renderPending can be flipped by callbacks during render
             if (this.renderPending) {
                 this.requestRender();
             }

package/dist/ui/terminal-ui.js

@@ -542,8 +542,9 @@ export class TerminalUI extends EventEmitter {
      */
     reRenderConversationWithVerbosity(verbosity) {
         const s = getStyles();
-        // Clear screen and scrollback buffer
-        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        // Clear screen and scrollback buffer (TTY-only — keep piped output clean)
+        if (process.stdout.isTTY)
+            process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
         // Reset footer state
         this.footer.resetRenderState();
         // Show mode indicator at top for temp modes
@@ -641,8 +642,9 @@ export class TerminalUI extends EventEmitter {
      * Called when verbose mode changes.
      */
     reRenderConversation() {
-        // Clear screen AND scrollback buffer, then move to home
-        process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        // Clear screen AND scrollback buffer, then move to home (TTY-only — keep piped output clean)
+        if (process.stdout.isTTY)
+            process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
         // Reset footer state since we cleared everything
         this.footer.resetRenderState();
         // Show filter indicator if active

package/dist/ui/terminal.d.ts

@@ -3,7 +3,16 @@
  *
  * Low-level terminal operations using ANSI escape codes.
  * Pure functions with no state.
+ *
+ * All output is gated through `ttyWrite()` so that pipes and redirected
+ * streams don't get raw escape sequences. `compilr | tee output.log`
+ * should produce a clean log, not a binary mess.
+ */
+/**
+ * Write a control sequence only when stdout is an interactive TTY.
+ * No-op when output is piped or redirected — keeps log files clean.
  */
+export declare function ttyWrite(seq: string): void;
 /**
  * Set terminal window title
  */

package/dist/ui/terminal.js

@@ -3,7 +3,20 @@
  *
  * Low-level terminal operations using ANSI escape codes.
  * Pure functions with no state.
+ *
+ * All output is gated through `ttyWrite()` so that pipes and redirected
+ * streams don't get raw escape sequences. `compilr | tee output.log`
+ * should produce a clean log, not a binary mess.
+ */
+/**
+ * Write a control sequence only when stdout is an interactive TTY.
+ * No-op when output is piped or redirected — keeps log files clean.
  */
+export function ttyWrite(seq) {
+    if (process.stdout.isTTY) {
+        process.stdout.write(seq);
+    }
+}
 // =============================================================================
 // Terminal Title
 // =============================================================================
@@ -11,7 +24,7 @@
  * Set terminal window title
  */
 export function setTitle(title) {
-    process.stdout.write(`\x1b]0;${title}\x07`);
+    ttyWrite(`\x1b]0;${title}\x07`);
 }
 // =============================================================================
 // Terminal Dimensions
@@ -36,7 +49,7 @@ export function getTerminalHeight() {
  */
 export function moveCursorUp(n) {
     if (n > 0) {
-        process.stdout.write(`\x1b[${String(n)}A`);
+        ttyWrite(`\x1b[${String(n)}A`);
     }
 }
 /**
@@ -44,32 +57,32 @@ export function moveCursorUp(n) {
  */
 export function moveCursorDown(n) {
     if (n > 0) {
-        process.stdout.write(`\x1b[${String(n)}B`);
+        ttyWrite(`\x1b[${String(n)}B`);
     }
 }
 /**
  * Move cursor to column (1-indexed)
  */
 export function moveCursorToColumn(col) {
-    process.stdout.write(`\x1b[${String(col)}G`);
+    ttyWrite(`\x1b[${String(col)}G`);
 }
 /**
  * Move cursor to beginning of line
  */
 export function moveCursorToLineStart() {
-    process.stdout.write('\r');
+    ttyWrite('\r');
 }
 /**
  * Save cursor position
  */
 export function saveCursor() {
-    process.stdout.write('\x1b[s');
+    ttyWrite('\x1b[s');
 }
 /**
  * Restore cursor position
  */
 export function restoreCursor() {
-    process.stdout.write('\x1b[u');
+    ttyWrite('\x1b[u');
 }
 // =============================================================================
 // Cursor Visibility
@@ -78,13 +91,13 @@ export function restoreCursor() {
  * Hide cursor
  */
 export function hideCursor() {
-    process.stdout.write('\x1b[?25l');
+    ttyWrite('\x1b[?25l');
 }
 /**
  * Show cursor
  */
 export function showCursor() {
-    process.stdout.write('\x1b[?25h');
+    ttyWrite('\x1b[?25h');
 }
 // =============================================================================
 // Clearing
@@ -93,13 +106,13 @@ export function showCursor() {
  * Clear current line
  */
 export function clearLine() {
-    process.stdout.write('\r\x1b[K');
+    ttyWrite('\r\x1b[K');
 }
 /**
  * Clear from cursor to end of screen
  */
 export function clearToEndOfScreen() {
-    process.stdout.write('\x1b[J');
+    ttyWrite('\x1b[J');
 }
 /**
  * Clear N lines above cursor (including current line)
@@ -118,7 +131,7 @@ export function clearLinesAbove(count) {
  * Clear entire screen
  */
 export function clearScreen() {
-    process.stdout.write('\x1b[2J\x1b[H');
+    ttyWrite('\x1b[2J\x1b[H');
 }
 /**
  * Enter alternate screen buffer.
@@ -131,14 +144,14 @@ export function enterAlternateScreen() {
     // \x1b[?1000l - disable mouse click tracking
     // \x1b[?1002l - disable mouse drag tracking
     // \x1b[?1003l - disable all mouse tracking
-    process.stdout.write('\x1b[?1049h\x1b[?1000l\x1b[?1002l\x1b[?1003l');
+    ttyWrite('\x1b[?1049h\x1b[?1000l\x1b[?1002l\x1b[?1003l');
 }
 /**
  * Leave alternate screen buffer.
  * Returns to main screen (previous content restored).
  */
 export function leaveAlternateScreen() {
-    process.stdout.write('\x1b[?1049l');
+    ttyWrite('\x1b[?1049l');
 }
 // =============================================================================
 // Line Calculations
@@ -305,5 +318,5 @@ export function writeLine(text = '') {
  * Ring terminal bell
  */
 export function bell() {
-    process.stdout.write('\x07');
+    ttyWrite('\x07');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "AI-powered coding assistant CLI using @compilr-dev/agents",
   "type": "module",
   "main": "dist/index.js",