@ekkos/cli 0.2.18 → 1.0.0

package/dist/index.js

@@ -42,12 +42,18 @@ const init_1 = require("./commands/init");
 const test_1 = require("./commands/test");
 const status_1 = require("./commands/status");
 const run_1 = require("./commands/run");
+const test_claude_1 = require("./commands/test-claude");
 const doctor_1 = require("./commands/doctor");
 const stream_1 = require("./commands/stream");
 const hooks_1 = require("./commands/hooks");
 const setup_remote_1 = require("./commands/setup-remote");
 const agent_1 = require("./commands/agent");
 const state_1 = require("./utils/state");
+const index_1 = require("./commands/usage/index");
+const dashboard_1 = require("./commands/dashboard");
+const swarm_1 = require("./commands/swarm");
+const swarm_dashboard_1 = require("./commands/swarm-dashboard");
+const swarm_setup_1 = require("./commands/swarm-setup");
 const chalk_1 = __importDefault(require("chalk"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -58,7 +64,158 @@ commander_1.program
     .name('ekkos')
     .description('ekkOS memory CLI for AI coding assistants')
     .version(pkg.version)
-    .addHelpText('beforeAll', chalk_1.default.cyan('\n  made by ekkOS_ with ❤️\n'));
+    .addHelpText('before', [
+    '',
+    chalk_1.default.cyan.bold('  ekkOS_') + chalk_1.default.gray(` v${pkg.version}`) + chalk_1.default.cyan('  —  Memory for AI coding assistants'),
+    chalk_1.default.gray('  https://docs.ekkos.dev'),
+    '',
+].join('\n'))
+    .addHelpText('after', [
+    '',
+    chalk_1.default.cyan.bold('Examples:'),
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Start Claude Code with ekkOS memory (default: run)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos init')}                         ${chalk_1.default.gray('First-time setup — authenticate + configure your IDE')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch with live usage dashboard (tmux split)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run -b')}                       ${chalk_1.default.gray('Launch with bypass permissions mode')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos doctor --fix')}                 ${chalk_1.default.gray('Check and auto-fix system prerequisites')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos usage daily')}                  ${chalk_1.default.gray("View today's token usage and costs")}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos swarm launch -t "build X"')}    ${chalk_1.default.gray('Launch parallel workers on a task')}`,
+    '',
+    chalk_1.default.gray('  Run ') + chalk_1.default.white('ekkos <command> --help') + chalk_1.default.gray(' for detailed options on any command.'),
+    '',
+].join('\n'))
+    .configureHelp({
+    formatHelp: (cmd, helper) => {
+        // Only customize root help — subcommands use default formatting
+        if (cmd.parent) {
+            // Fall back to default formatting for subcommands
+            const termWidth = helper.padWidth(cmd, helper);
+            const helpWidth = helper.helpWidth || 80;
+            const itemIndentWidth = 2;
+            const itemSeparatorWidth = 2;
+            let output = '';
+            // Description
+            const desc = helper.commandDescription(cmd);
+            if (desc) {
+                output += desc + '\n\n';
+            }
+            // Usage
+            output += chalk_1.default.cyan.bold('Usage:') + ' ' + helper.commandUsage(cmd) + '\n';
+            // Arguments
+            const args = helper.visibleArguments(cmd);
+            if (args.length > 0) {
+                output += '\n' + chalk_1.default.cyan.bold('Arguments:') + '\n';
+                for (const arg of args) {
+                    const term = helper.argumentTerm(arg);
+                    const desc = helper.argumentDescription(arg);
+                    output += `  ${chalk_1.default.green(term.padEnd(termWidth + itemSeparatorWidth))}${desc}\n`;
+                }
+            }
+            // Options
+            const opts = helper.visibleOptions(cmd);
+            if (opts.length > 0) {
+                output += '\n' + chalk_1.default.cyan.bold('Options:') + '\n';
+                for (const opt of opts) {
+                    const term = helper.optionTerm(opt);
+                    const desc = helper.optionDescription(opt);
+                    output += `  ${chalk_1.default.green(term.padEnd(termWidth + itemSeparatorWidth))}${desc}\n`;
+                }
+            }
+            // Subcommands
+            const cmds = helper.visibleCommands(cmd);
+            if (cmds.length > 0) {
+                output += '\n' + chalk_1.default.cyan.bold('Commands:') + '\n';
+                for (const sub of cmds) {
+                    const term = helper.subcommandTerm(sub);
+                    const desc = helper.subcommandDescription(sub);
+                    output += `  ${chalk_1.default.green(term.padEnd(termWidth + itemSeparatorWidth))}${desc}\n`;
+                }
+            }
+            return output;
+        }
+        // ── Root help: grouped command listing ──
+        const commands = helper.visibleCommands(cmd);
+        const cmdMap = new Map();
+        for (const sub of commands) {
+            cmdMap.set(sub.name(), {
+                term: helper.subcommandTerm(sub),
+                desc: helper.subcommandDescription(sub),
+            });
+        }
+        const groups = [
+            {
+                title: 'Getting Started',
+                icon: '▸',
+                commands: [
+                    { name: 'init', desc: 'Authenticate and configure your IDE (Claude, Cursor, Windsurf)' },
+                    { name: 'status', desc: 'Show memory status and installation info' },
+                    { name: 'test', desc: 'Test connection to ekkOS memory API' },
+                    { name: 'doctor', desc: 'Check system prerequisites (Node, PTY, Claude, MCP)' },
+                ],
+            },
+            {
+                title: 'Running',
+                icon: '▸',
+                commands: [
+                    { name: 'run', desc: 'Launch Claude Code with ekkOS memory + auto-continue', note: 'default' },
+                    { name: 'test-claude', desc: 'Launch Claude with proxy only (no ccDNA/PTY) for debugging' },
+                    { name: 'sessions', desc: 'List active Claude Code sessions' },
+                ],
+            },
+            {
+                title: 'Monitoring & Usage',
+                icon: '▸',
+                commands: [
+                    { name: 'usage', desc: 'Token usage and cost tracking (daily, weekly, monthly, session)' },
+                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
+                    { name: 'stream', desc: 'Stream capture status and management' },
+                    { name: 'hooks', desc: 'Install, verify, and manage ekkOS hooks' },
+                ],
+            },
+            {
+                title: 'Remote Terminal',
+                icon: '▸',
+                commands: [
+                    { name: 'setup-remote', desc: 'Set up remote access (run Claude on your PC from anywhere)' },
+                    { name: 'agent', desc: 'Manage the remote terminal agent (start, stop, status, logs)' },
+                ],
+            },
+            {
+                title: 'Swarm (Multi-Agent)',
+                icon: '▸',
+                commands: [
+                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, swarm dashboard' },
+                ],
+            },
+        ];
+        const padCmd = 18;
+        let output = '';
+        output += chalk_1.default.cyan.bold('Usage:') + ` ekkos ${chalk_1.default.gray('[command] [options]')}\n`;
+        for (const group of groups) {
+            output += '\n' + chalk_1.default.cyan.bold(`${group.icon} ${group.title}`) + '\n';
+            for (const c of group.commands) {
+                const nameStr = c.note
+                    ? chalk_1.default.green(c.name) + chalk_1.default.gray(` (${c.note})`)
+                    : chalk_1.default.green(c.name);
+                // Compute visible length for padding (strip ANSI)
+                const visLen = c.note ? c.name.length + ` (${c.note})`.length : c.name.length;
+                const pad = Math.max(1, padCmd - visLen);
+                output += `  ${nameStr}${' '.repeat(pad)}${chalk_1.default.gray(c.desc)}\n`;
+            }
+        }
+        // Options
+        const opts = helper.visibleOptions(cmd);
+        if (opts.length > 0) {
+            output += '\n' + chalk_1.default.cyan.bold('Options:') + '\n';
+            for (const opt of opts) {
+                const term = helper.optionTerm(opt);
+                const desc = helper.optionDescription(opt);
+                output += `  ${chalk_1.default.green(term.padEnd(22))}${desc}\n`;
+            }
+        }
+        return output;
+    },
+});
 // Main init command (combined auth + setup)
 commander_1.program
     .command('init')
@@ -88,15 +245,39 @@ commander_1.program
     .option('-v, --verbose', 'Show debug output')
     .option('-d, --doctor', 'Run diagnostics before starting')
     .option('-r, --research', 'Auto-run research agent on startup (scans arXiv for new AI papers)')
-    .option('--no-inject', 'Monitor-only mode (detect context wall but print instructions instead of auto-inject)')
+    .option('--skip-inject', 'Monitor-only mode (detect context wall but print instructions instead of auto-inject)')
+    .option('--skip-dna', 'Skip ccDNA injection (bypass Claude Code patching)')
+    .option('--skip-proxy', 'Skip API proxy (use direct Anthropic API, disables seamless context eviction)')
+    .option('--dashboard', 'Launch with live usage dashboard in an isolated 60/40 tmux split (requires tmux)')
+    .option('--kickstart', 'Auto-send "test" on load to create session immediately (used internally by --dashboard)')
+    .option('--add-dir <dirs...>', 'Additional directories Claude Code can access (outside working directory)')
     .action((options) => {
     (0, run_1.run)({
         session: options.session,
         bypass: options.bypass,
         verbose: options.verbose,
         doctor: options.doctor,
-        noInject: options.noInject,
-        research: options.research
+        noInject: options.skipInject,
+        research: options.research,
+        noDna: options.skipDna,
+        noProxy: options.skipProxy,
+        dashboard: options.dashboard,
+        kickstart: options.kickstart,
+        addDirs: options.addDir,
+    });
+});
+// Test Claude — bare proxy test (no CLI wrapper)
+commander_1.program
+    .command('test-claude')
+    .description('Launch Claude Code with proxy only (no ccDNA, no PTY, no injections) for debugging')
+    .option('--no-proxy', 'Skip proxy too (completely vanilla Claude)')
+    .option('--no-hooks', 'Temporarily disable all hooks during test')
+    .option('-v, --verbose', 'Show debug output')
+    .action((options) => {
+    (0, test_claude_1.testClaude)({
+        noProxy: options.proxy === false,
+        noHooks: options.hooks === false,
+        verbose: options.verbose,
     });
 });
 // Doctor command - check system prerequisites
@@ -169,6 +350,10 @@ hooksCmd
     .action((options) => {
     (0, hooks_1.hooksStatus)({ verbose: options.verbose });
 });
+// Usage command - track Claude Code token usage and costs (powered by ccusage)
+(0, index_1.registerUsageCommand)(commander_1.program);
+// Dashboard command - live TUI for monitoring session usage
+commander_1.program.addCommand(dashboard_1.dashboardCommand);
 // Sessions command - list active Claude Code sessions (swarm support)
 commander_1.program
     .command('sessions')
@@ -201,7 +386,7 @@ commander_1.program
         }
     }
 });
-// Deprecated setup command (redirects to init)
+// Deprecated setup command (redirects to init) — hidden from root help by custom formatHelp
 commander_1.program
     .command('setup')
     .description('[DEPRECATED] Use "ekkos init" instead')
@@ -290,4 +475,76 @@ agentCmd
     .action((options) => {
     (0, agent_1.agentLogs)({ follow: options.follow });
 });
+agentCmd
+    .command('health')
+    .description('Check agent daemon health and diagnose connection issues')
+    .option('-j, --json', 'Output machine-readable JSON')
+    .action((options) => {
+    (0, agent_1.agentHealth)({ json: options.json });
+});
+// Swarm command - manage Q-learning routing
+const swarmCmd = commander_1.program
+    .command('swarm')
+    .description('Manage Swarm Q-learning model routing');
+swarmCmd
+    .command('status')
+    .description('Show Q-table stats (states, visits, epsilon, top actions)')
+    .action(swarm_1.swarmStatus);
+swarmCmd
+    .command('reset')
+    .description('Clear Q-table from Redis (routing reverts to static rules)')
+    .action(swarm_1.swarmReset);
+swarmCmd
+    .command('export')
+    .description('Export Q-table to .swarm/q-learning-model.json')
+    .action(swarm_1.swarmExport);
+swarmCmd
+    .command('import')
+    .description('Import Q-table from .swarm/q-learning-model.json into Redis')
+    .action(swarm_1.swarmImport);
+swarmCmd
+    .command('launch')
+    .description('Launch parallel workers on a decomposed task (opens wizard if --task is omitted)')
+    .option('-w, --workers <count>', 'Number of parallel workers (2-8)', parseInt)
+    .option('-t, --task <task>', 'Task description to decompose and execute')
+    .option('--no-bypass', 'Disable bypass permissions mode')
+    .option('--no-decompose', 'Skip AI decomposition (send same task to all workers)')
+    .option('--no-queen', 'Skip launching the Python Queen coordinator')
+    .option('--queen-strategy <strategy>', 'Queen strategy (adaptive-default, hierarchical-cascade, mesh-consensus)')
+    .option('-v, --verbose', 'Show debug output')
+    .action((options) => {
+    // Auto-open wizard when --task is missing
+    if (!options.task) {
+        (0, swarm_setup_1.swarmSetup)();
+        return;
+    }
+    (0, swarm_1.swarmLaunch)({
+        workers: options.workers || 4,
+        task: options.task,
+        bypass: options.bypass !== false,
+        noDecompose: options.decompose === false,
+        noQueen: options.queen === false,
+        queenStrategy: options.queenStrategy,
+        verbose: options.verbose,
+    });
+});
+swarmCmd
+    .command('setup')
+    .description('Interactive TUI wizard for configuring and launching a swarm')
+    .action(() => {
+    (0, swarm_setup_1.swarmSetup)();
+});
+swarmCmd.addCommand(swarm_dashboard_1.swarmDashboardCommand);
+// Handle `-help` (single dash) — rewrite to `--help` for Commander compatibility
+const helpIdx = process.argv.indexOf('-help');
+if (helpIdx !== -1) {
+    process.argv[helpIdx] = '--help';
+}
+// Default to `run` if no command specified (e.g. `ekkos`, `ekkos -b --dashboard`)
+const knownCommands = commander_1.program.commands.map(c => c.name());
+const userArgs = process.argv.slice(2);
+const hasCommand = userArgs.some(a => knownCommands.includes(a) || a === 'help' || a === '--help' || a === '-h' || a === '--version' || a === '-V');
+if (!hasCommand) {
+    process.argv.splice(2, 0, 'run');
+}
 commander_1.program.parse();

package/dist/lib/tmux-scrollbar.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * tmux-scrollbar.ts
+ *
+ * A thin visual scrollbar (2 columns wide) that runs in its own narrow tmux pane.
+ * It tracks the scroll position of a target pane (Claude Code) and renders a
+ * proportional scrollbar thumb. Supports click-to-jump and drag-to-scroll.
+ *
+ * Usage: node tmux-scrollbar.js <target-pane>
+ * Example: node tmux-scrollbar.js :.0
+ *
+ * Layout: [Claude Code (68%)] [Scrollbar (2col)] [Dashboard (30%)]
+ */
+export {};

package/dist/lib/tmux-scrollbar.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * tmux-scrollbar.ts
+ *
+ * A thin visual scrollbar (2 columns wide) that runs in its own narrow tmux pane.
+ * It tracks the scroll position of a target pane (Claude Code) and renders a
+ * proportional scrollbar thumb. Supports click-to-jump and drag-to-scroll.
+ *
+ * Usage: node tmux-scrollbar.js <target-pane>
+ * Example: node tmux-scrollbar.js :.0
+ *
+ * Layout: [Claude Code (68%)] [Scrollbar (2col)] [Dashboard (30%)]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const TARGET_PANE = process.argv[2] || ':.0';
+const POLL_MS = 200;
+// ── ANSI escape sequences ──
+const ESC = '\x1b';
+const CSI = `${ESC}[`;
+const ansi = {
+    clear: `${CSI}2J`,
+    home: `${CSI}H`,
+    hideCursor: `${CSI}?25l`,
+    showCursor: `${CSI}?25h`,
+    // SGR extended mouse protocol: supports coordinates > 223
+    enableMouse: `${CSI}?1000h${CSI}?1002h${CSI}?1006h`,
+    disableMouse: `${CSI}?1000l${CSI}?1002l${CSI}?1006l`,
+    reset: `${CSI}0m`,
+    moveTo: (row, col) => `${CSI}${row};${col}H`,
+    // 256-color mode
+    fg256: (n) => `${CSI}38;5;${n}m`,
+    bg256: (n) => `${CSI}48;5;${n}m`,
+};
+// ── Color scheme (matches dashboard cyan theme) ──
+const COLORS = {
+    thumbFg: ansi.fg256(44), // Cyan thumb
+    thumbBg: ansi.bg256(23), // Dark cyan background
+    thumbActiveFg: ansi.fg256(51), // Bright cyan when dragging
+    thumbActiveBg: ansi.bg256(30), // Brighter dark cyan when dragging
+    trackFg: ansi.fg256(236), // Very dark gray track dots
+    trackBg: ansi.bg256(233), // Near-black background
+    labelFg: ansi.fg256(240), // Dim label text
+};
+// ── State ──
+let lastRenderedFrame = '';
+let isDragging = false;
+let pollTimer;
+function getHeight() {
+    return process.stdout.rows || 40;
+}
+/**
+ * Query tmux for the target pane's scroll position.
+ * Returns { inMode, scrollPos, historySize, paneHeight }
+ */
+function getPaneInfo() {
+    try {
+        const raw = (0, child_process_1.execSync)(`tmux display-message -p -t "${TARGET_PANE}" ` +
+            `'#{pane_in_mode}|#{scroll_position}|#{history_size}|#{pane_height}'`, { encoding: 'utf-8', timeout: 800, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const [mode, pos, hist, ph] = raw.split('|');
+        return {
+            inMode: mode === '1',
+            scrollPos: parseInt(pos) || 0,
+            historySize: parseInt(hist) || 0,
+            paneHeight: parseInt(ph) || 40,
+        };
+    }
+    catch {
+        return { inMode: false, scrollPos: 0, historySize: 0, paneHeight: 40 };
+    }
+}
+/**
+ * Render the scrollbar to stdout using ANSI escape codes.
+ * Only redraws if the frame has changed (diffing).
+ */
+function render() {
+    const height = getHeight();
+    const info = getPaneInfo();
+    // Total scrollable content
+    const totalLines = info.historySize + info.paneHeight;
+    if (totalLines <= 0)
+        return;
+    // Thumb size proportional to viewport/total
+    const viewportRatio = Math.min(1, info.paneHeight / totalLines);
+    const thumbSize = Math.max(2, Math.round(viewportRatio * height));
+    // Thumb position
+    let thumbTop;
+    if (!info.inMode || info.historySize === 0) {
+        // Live output — thumb at bottom
+        thumbTop = height - thumbSize;
+    }
+    else {
+        // Copy mode — scroll_position = lines from bottom
+        const scrollFraction = Math.min(1, info.scrollPos / Math.max(1, info.historySize));
+        thumbTop = Math.round((1 - scrollFraction) * (height - thumbSize));
+    }
+    // Clamp
+    thumbTop = Math.max(0, Math.min(height - thumbSize, thumbTop));
+    // Build frame string
+    const fgColor = isDragging ? COLORS.thumbActiveFg : COLORS.thumbFg;
+    const bgColor = isDragging ? COLORS.thumbActiveBg : COLORS.thumbBg;
+    let frame = ansi.home;
+    for (let y = 0; y < height; y++) {
+        const isThumb = y >= thumbTop && y < thumbTop + thumbSize;
+        frame += ansi.moveTo(y + 1, 1);
+        if (isThumb) {
+            frame += `${fgColor}${bgColor}██${ansi.reset}`;
+        }
+        else {
+            frame += `${COLORS.trackFg}${COLORS.trackBg}░░${ansi.reset}`;
+        }
+    }
+    // Only write if changed
+    if (frame !== lastRenderedFrame) {
+        process.stdout.write(frame);
+        lastRenderedFrame = frame;
+    }
+}
+/**
+ * Scroll the target pane to a position based on scrollbar click location.
+ */
+function scrollToPosition(y) {
+    const height = getHeight();
+    const info = getPaneInfo();
+    if (info.historySize <= 0)
+        return;
+    const ratio = Math.max(0, Math.min(1, y / Math.max(1, height - 1)));
+    // If clicking at the very bottom, exit copy-mode for live output
+    if (ratio >= 0.95) {
+        try {
+            if (info.inMode) {
+                (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X cancel`, {
+                    timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+        }
+        catch { /* ignore */ }
+        lastRenderedFrame = '';
+        render();
+        return;
+    }
+    // Target line from top of scrollback
+    const targetLine = Math.round(ratio * info.historySize);
+    try {
+        // Enter copy-mode if not already
+        if (!info.inMode) {
+            (0, child_process_1.execSync)(`tmux copy-mode -t "${TARGET_PANE}"`, {
+                timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        // Jump to target line using goto-line (tmux 3.1+)
+        // Fallback: history-top + cursor-down for older tmux
+        try {
+            (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X goto-line ${targetLine}`, {
+                timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            // Fallback for older tmux: go to top, then move down
+            (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X history-top`, {
+                timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (targetLine > 0) {
+                // Move in chunks to avoid command-line length limits
+                let remaining = targetLine;
+                while (remaining > 0) {
+                    const chunk = Math.min(remaining, 5000);
+                    (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X -N ${chunk} cursor-down`, {
+                        timeout: 1000, stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                    remaining -= chunk;
+                }
+            }
+        }
+    }
+    catch { /* ignore scroll errors */ }
+    lastRenderedFrame = '';
+    render();
+}
+/**
+ * Refocus the target pane (Claude Code) after scrollbar interaction.
+ */
+function refocusTarget() {
+    try {
+        (0, child_process_1.execSync)(`tmux select-pane -t "${TARGET_PANE}"`, {
+            timeout: 300, stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch { /* ignore */ }
+}
+// ── Mouse event handling ──
+function handleInput(data) {
+    const str = data.toString();
+    // Parse SGR mouse events: ESC [ < button ; x ; y M (press) / m (release)
+    const events = str.matchAll(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/g);
+    for (const match of events) {
+        const button = parseInt(match[1]);
+        const y = parseInt(match[3]) - 1; // Convert to 0-indexed
+        const isPress = match[4] === 'M';
+        if (button === 0) {
+            // Left mouse button
+            if (isPress) {
+                isDragging = true;
+                scrollToPosition(y);
+            }
+            else {
+                // Release
+                if (isDragging) {
+                    isDragging = false;
+                    lastRenderedFrame = '';
+                    render();
+                    // Return focus to Claude Code pane after click
+                    refocusTarget();
+                }
+            }
+        }
+        else if (button === 32 && isDragging) {
+            // Left button drag (SGR reports button 32 for motion with button 0 held)
+            scrollToPosition(y);
+        }
+        else if (button === 64) {
+            // Scroll wheel up — forward to target pane
+            try {
+                const info = getPaneInfo();
+                if (!info.inMode) {
+                    (0, child_process_1.execSync)(`tmux copy-mode -t "${TARGET_PANE}" -e`, {
+                        timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                }
+                (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X -N 5 scroll-up`, {
+                    timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch { /* ignore */ }
+            lastRenderedFrame = '';
+            render();
+        }
+        else if (button === 65) {
+            // Scroll wheel down — forward to target pane
+            try {
+                (0, child_process_1.execSync)(`tmux send-keys -t "${TARGET_PANE}" -X -N 5 scroll-down`, {
+                    timeout: 500, stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch { /* ignore */ }
+            lastRenderedFrame = '';
+            render();
+        }
+        return; // Processed mouse event
+    }
+    // Keyboard input
+    if (str === 'q' || str === '\x03') {
+        // Quit on 'q' or Ctrl-C
+        shutdown();
+    }
+}
+// ── Lifecycle ──
+function setup() {
+    // Hide cursor, enable mouse tracking, clear screen
+    process.stdout.write(ansi.hideCursor + ansi.enableMouse + ansi.clear);
+    // Raw mode for stdin (capture mouse events)
+    if (process.stdin.setRawMode) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.on('data', handleInput);
+    // Handle terminal resize
+    process.stdout.on('resize', () => {
+        lastRenderedFrame = '';
+        render();
+    });
+}
+function cleanup() {
+    process.stdout.write(ansi.showCursor + ansi.disableMouse + ansi.reset + ansi.clear);
+    if (process.stdin.setRawMode) {
+        try {
+            process.stdin.setRawMode(false);
+        }
+        catch { /* ignore */ }
+    }
+}
+function shutdown() {
+    clearInterval(pollTimer);
+    cleanup();
+    process.exit(0);
+}
+// Graceful exit
+process.on('exit', cleanup);
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+process.on('SIGHUP', shutdown);
+// ── Main ──
+setup();
+render();
+pollTimer = setInterval(render, POLL_MS);

package/dist/lib/usage-monitor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Simple usage monitoring for ekkOS embedding costs
+ * Tracks daily usage to prevent runaway costs
+ */
+interface UsageRecord {
+    date: string;
+    embeddings: number;
+    cost: number;
+    model: string;
+}
+interface DailyUsage {
+    date: string;
+    totalEmbeddings: number;
+    totalCost: number;
+    byModel: Record<string, {
+        count: number;
+        cost: number;
+    }>;
+}
+/**
+ * Load usage records
+ */
+export declare function loadUsage(): Promise<UsageRecord[]>;
+/**
+ * Record an embedding generation
+ */
+export declare function recordEmbedding(model?: string, tokens?: number): Promise<void>;
+/**
+ * Get usage for a specific date
+ */
+export declare function getUsageForDate(date: string): Promise<DailyUsage>;
+/**
+ * Get usage for the last N days
+ */
+export declare function getUsageForDays(days: number): Promise<DailyUsage[]>;
+/**
+ * Check if usage exceeds threshold
+ */
+export declare function checkThreshold(dailyLimit?: number, costLimit?: number): Promise<{
+    exceeded: boolean;
+    usage: DailyUsage;
+}>;
+/**
+ * Clear old usage data (keep last 90 days)
+ */
+export declare function pruneOldUsage(): Promise<void>;
+export {};