@ekkos/cli 0.3.3 → 1.0.1

package/dist/commands/usage/session.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionCommand = sessionCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage session [id] [--list] [--instance id] [--json]
+ *
+ * Accepts ekkOS 3-word names (lit-lex-zip) or ccusage project paths.
+ */
+async function sessionCommand(options) {
+    const instanceId = options.instance;
+    if (options.list) {
+        await listSessions(instanceId, options.json);
+        return;
+    }
+    if (!options.sessionId) {
+        await listSessions(instanceId, options.json);
+        return;
+    }
+    try {
+        let usage = null;
+        // Detect ekkOS 3-word session names and resolve via active-sessions.json
+        if ((0, usage_parser_js_1.isEkkosSessionName)(options.sessionId)) {
+            usage = await (0, usage_parser_js_1.getSessionUsageByName)(options.sessionId);
+            if (!usage) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: `ekkOS session "${options.sessionId}" not found` }));
+                    return;
+                }
+                console.log(chalk_1.default.yellow(`  ekkOS session "${options.sessionId}" not found.`));
+                console.log(chalk_1.default.gray('  Check available sessions with: ekkos usage session -l'));
+                return;
+            }
+        }
+        else {
+            // Fallback to ccusage project-path lookup
+            usage = await (0, usage_parser_js_1.getSessionUsage)(options.sessionId, instanceId);
+        }
+        if (!usage) {
+            if (options.json) {
+                console.log(JSON.stringify({ error: 'Session not found' }));
+                return;
+            }
+            console.log(chalk_1.default.yellow(`  No usage data found for session: ${options.sessionId}`));
+            return;
+        }
+        if (options.json) {
+            console.log(JSON.stringify(usage, null, 2));
+            return;
+        }
+        displaySessionUsage(usage);
+    }
+    catch (err) {
+        console.log(chalk_1.default.red(`  Error: ${err.message}`));
+    }
+}
+/** Display session usage in formatted table */
+function displaySessionUsage(usage) {
+    (0, formatters_js_1.titleBar)(`Session: ${usage.session_name}`, usage.session_id);
+    (0, formatters_js_1.sectionHeader)('Summary');
+    console.log(`  ${chalk_1.default.bold('Session ID:')}      ${usage.session_id}`);
+    console.log(`  ${chalk_1.default.bold('Turn Count:')}      ${chalk_1.default.green(usage.turn_count.toString())}`);
+    console.log(`  ${chalk_1.default.bold('Total Tokens:')}    ${(0, formatters_js_1.formatNumber)(usage.total_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Avg Context:')}     ${(0, formatters_js_1.formatPercentage)(usage.avg_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Max Context:')}     ${(0, formatters_js_1.formatPercentage)(usage.max_context_percentage)}`);
+    console.log(`  ${chalk_1.default.bold('Started:')}         ${(0, formatters_js_1.formatTimestamp)(usage.started_at)}`);
+    console.log(`  ${chalk_1.default.bold('Last Activity:')}   ${(0, formatters_js_1.formatTimestamp)(usage.last_activity)}`);
+    console.log();
+    (0, formatters_js_1.sectionHeader)('Token Breakdown');
+    console.log(`  ${chalk_1.default.bold('Input Tokens:')}       ${(0, formatters_js_1.formatNumber)(usage.total_input_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Output Tokens:')}      ${(0, formatters_js_1.formatNumber)(usage.total_output_tokens)}`);
+    console.log(`  ${chalk_1.default.bold('Cache Read:')}         ${(0, formatters_js_1.formatNumber)(usage.total_cache_read_tokens)} ${chalk_1.default.gray('(90% discount)')}`);
+    console.log(`  ${chalk_1.default.bold('Cache Creation:')}     ${(0, formatters_js_1.formatNumber)(usage.total_cache_creation_tokens)} ${chalk_1.default.gray('(25% premium)')}`);
+    console.log();
+    (0, formatters_js_1.sectionHeader)('Cost');
+    console.log(`  ${chalk_1.default.bold('Total Cost:')}  ${chalk_1.default.green((0, formatters_js_1.formatCost)(usage.total_cost))}`);
+    console.log(`  ${chalk_1.default.bold('Models Used:')} ${chalk_1.default.cyan(usage.models_used.join(', '))}`);
+    console.log();
+    // ekkOS pattern metrics
+    if (usage.patterns_retrieved !== undefined) {
+        (0, formatters_js_1.sectionHeader)('ekkOS Pattern Metrics');
+        console.log(`  ${chalk_1.default.bold('Patterns Retrieved:')}  ${chalk_1.default.cyan(usage.patterns_retrieved.toString())}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Applied:')}    ${chalk_1.default.green(usage.patterns_applied?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Patterns Learned:')}    ${chalk_1.default.yellow(usage.patterns_learned?.toString() || '0')}`);
+        console.log(`  ${chalk_1.default.bold('Confidence Gain:')}     ${chalk_1.default.magenta(`+${((usage.confidence_gain || 0) * 100).toFixed(1)}%`)}`);
+        console.log();
+    }
+    // Turn-by-turn breakdown
+    if (usage.turns.length > 0) {
+        (0, formatters_js_1.sectionHeader)('Turn-by-Turn Breakdown');
+        console.log(chalk_1.default.gray('  Turn │ Context % │  Input │ Output │ Cache Read │   Total'));
+        console.log(chalk_1.default.gray('─'.repeat(80)));
+        for (const turn of usage.turns) {
+            const turnStr = turn.turn_number.toString().padStart(4);
+            const contextStr = (0, formatters_js_1.formatPercentage)(turn.context_percentage).padStart(10);
+            const inputStr = (0, formatters_js_1.formatNumber)(turn.input_tokens).padStart(7);
+            const outputStr = (0, formatters_js_1.formatNumber)(turn.output_tokens).padStart(7);
+            const cacheStr = (0, formatters_js_1.formatNumber)(turn.cache_read_tokens).padStart(11);
+            const totalStr = (0, formatters_js_1.formatNumber)(turn.total_tokens).padStart(8);
+            const contextColor = (0, formatters_js_1.getContextColor)(turn.context_percentage);
+            console.log(`  ${turnStr} │ ${contextColor(contextStr)} │ ${inputStr} │ ${outputStr} │ ${cacheStr} │ ${totalStr}`);
+        }
+        console.log();
+    }
+    // VM validation
+    if (usage.turn_count >= 5) {
+        const contextValues = usage.turns.map(t => t.context_percentage);
+        const range = Math.max(...contextValues) - Math.min(...contextValues);
+        if (range < 15) {
+            console.log(chalk_1.default.green.bold('  VM Working: Context staying in constant band'));
+        }
+        else {
+            console.log(chalk_1.default.yellow.bold('  VM Warning: Context growing linearly (check proxy eviction)'));
+        }
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}
+/** List available sessions - shows ekkOS sessions by default, falls back to ccusage */
+async function listSessions(instanceId, json) {
+    // Try ekkOS sessions first (individual sessions with 3-word names)
+    const ekkosSessions = await (0, usage_parser_js_1.listEkkosSessions)(30);
+    if (ekkosSessions.length > 0) {
+        if (json) {
+            console.log(JSON.stringify(ekkosSessions, null, 2));
+            return;
+        }
+        (0, formatters_js_1.titleBar)('ekkOS Sessions', `${ekkosSessions.length} recent`);
+        // Find max cost for bar rendering
+        const maxCost = Math.max(...ekkosSessions.map(s => s.cost), 0.01);
+        console.log(chalk_1.default.gray('  Session Name        │ Turns │    Cost │   Tokens │ Models                  │ Started'));
+        console.log(chalk_1.default.gray('  ' + '─'.repeat(100)));
+        for (const s of ekkosSessions) {
+            const name = chalk_1.default.bold.cyan(s.name.padEnd(20));
+            const turns = s.turnCount.toString().padStart(5);
+            const cost = chalk_1.default.green((0, formatters_js_1.formatCost)(s.cost).padStart(7));
+            const tokens = (0, formatters_js_1.formatCompact)(s.tokens).padStart(8);
+            const models = chalk_1.default.gray(s.models
+                .filter(m => !m.includes('synthetic'))
+                .map(m => {
+                if (m.includes('opus-4-6'))
+                    return 'opus-4.6';
+                if (m.includes('opus-4-5'))
+                    return 'opus-4.5';
+                if (m.includes('sonnet-4-5'))
+                    return 'sonnet-4.5';
+                if (m.includes('haiku-4-5'))
+                    return 'haiku-4.5';
+                return m;
+            }).join(', ').padEnd(24));
+            const started = chalk_1.default.gray((0, formatters_js_1.formatTimestamp)(s.startedAt));
+            const bar = (0, formatters_js_1.renderBar)(s.cost, maxCost, 8);
+            console.log(`  ${name}│ ${turns} │ ${cost} │ ${tokens} │ ${models}│ ${started} ${bar}`);
+        }
+        console.log();
+        console.log(chalk_1.default.gray('  Use: ekkos usage session <name>  for detailed breakdown'));
+        console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+        console.log();
+        return;
+    }
+    // Fallback to ccusage project-level sessions
+    const sessions = await (0, usage_parser_js_1.getAllSessions)(instanceId);
+    if (sessions.length === 0) {
+        if (json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('session');
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Sessions', `${sessions.length} found`);
+    const sorted = [...sessions].sort((a, b) => (b.last_activity || '').localeCompare(a.last_activity || ''));
+    for (const session of sorted) {
+        console.log(`  ${chalk_1.default.bold(session.session_id)}`);
+        console.log(`    ${chalk_1.default.gray('Cost:')} ${chalk_1.default.green((0, formatters_js_1.formatCost)(session.total_cost))}` +
+            `  ${chalk_1.default.gray('Tokens:')} ${(0, formatters_js_1.formatCompact)(session.total_tokens)}` +
+            `  ${chalk_1.default.gray('Last:')} ${session.last_activity}` +
+            `  ${chalk_1.default.gray('Models:')} ${chalk_1.default.cyan(session.models_used.join(', '))}`);
+        console.log();
+    }
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/commands/usage/weekly.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ekkos usage weekly [--weeks N] [--json]
+ *
+ * Show weekly usage breakdown
+ */
+export declare function weeklyCommand(options: {
+    weeks?: number;
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/usage/weekly.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weeklyCommand = weeklyCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const usage_parser_js_1 = require("../../lib/usage-parser.js");
+const formatters_js_1 = require("./formatters.js");
+/**
+ * ekkos usage weekly [--weeks N] [--json]
+ *
+ * Show weekly usage breakdown
+ */
+async function weeklyCommand(options) {
+    const weeks = options.weeks || 8;
+    const data = await (0, usage_parser_js_1.getWeeklyUsage)();
+    if (data.length === 0) {
+        if (options.json) {
+            console.log(JSON.stringify([]));
+            return;
+        }
+        (0, formatters_js_1.noData)('weekly usage');
+        return;
+    }
+    // Sort by week date descending
+    const sorted = [...data].sort((a, b) => (b.week || '').localeCompare(a.week || ''));
+    const recent = sorted.slice(0, weeks);
+    if (options.json) {
+        console.log(JSON.stringify(recent, null, 2));
+        return;
+    }
+    (0, formatters_js_1.titleBar)('Weekly Usage Report', `Last ${Math.min(weeks, recent.length)} weeks`);
+    const maxCost = Math.max(...recent.map(w => w.totalCost || 0));
+    let totalCost = 0;
+    console.log(chalk_1.default.gray('  Week of'.padEnd(22)) +
+        chalk_1.default.gray('│ ') +
+        chalk_1.default.gray('Cost'.padStart(10)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Input'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Output'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Cache'.padStart(8)) +
+        chalk_1.default.gray(' │ ') +
+        chalk_1.default.gray('Chart'));
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    for (const week of recent) {
+        const cost = week.totalCost || 0;
+        totalCost += cost;
+        const weekDate = (0, formatters_js_1.formatDate)(week.week || '');
+        const bar = (0, formatters_js_1.renderBar)(cost, maxCost, 14);
+        console.log(`  ${chalk_1.default.white(weekDate.padEnd(20))} │ ${chalk_1.default.green((0, formatters_js_1.formatCost)(cost).padStart(10))} │ ${(0, formatters_js_1.formatCompact)(week.inputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(week.outputTokens || 0).padStart(8)} │ ${(0, formatters_js_1.formatCompact)(week.cacheReadTokens || 0).padStart(8)} │ ${bar}`);
+    }
+    console.log(chalk_1.default.gray('─'.repeat(80)));
+    console.log(chalk_1.default.bold('  TOTAL'.padEnd(22)) +
+        `│ ${chalk_1.default.green.bold((0, formatters_js_1.formatCost)(totalCost).padStart(10))} │`);
+    console.log();
+    console.log(chalk_1.default.bold.cyan('═'.repeat(80)));
+    console.log();
+}

package/dist/deploy/instructions.d.ts

@@ -1,9 +1,12 @@
 /**
- * Deploy CLAUDE.md to ~/.claude/CLAUDE.md
+ * Deploy ekkOS instructions to ~/.claude/rules/ekkos.md
+ *
+ * Uses Claude Code's user-level rules directory — auto-loaded for all projects
+ * without touching the user's existing CLAUDE.md.
  */
 export declare function deployInstructions(): void;
 /**
- * Check if CLAUDE.md is deployed
+ * Check if ekkOS instructions are deployed
  */
 export declare function isInstructionsDeployed(): boolean;
 /**

package/dist/deploy/instructions.js

@@ -7,21 +7,24 @@ const fs_1 = require("fs");
 const platform_1 = require("../utils/platform");
 const templates_1 = require("../utils/templates");
 /**
- * Deploy CLAUDE.md to ~/.claude/CLAUDE.md
+ * Deploy ekkOS instructions to ~/.claude/rules/ekkos.md
+ *
+ * Uses Claude Code's user-level rules directory — auto-loaded for all projects
+ * without touching the user's existing CLAUDE.md.
  */
 function deployInstructions() {
-    // Ensure .claude directory exists
-    if (!(0, fs_1.existsSync)(platform_1.CLAUDE_DIR)) {
-        (0, fs_1.mkdirSync)(platform_1.CLAUDE_DIR, { recursive: true });
+    // Ensure ~/.claude/rules/ exists
+    if (!(0, fs_1.existsSync)(platform_1.CLAUDE_RULES_DIR)) {
+        (0, fs_1.mkdirSync)(platform_1.CLAUDE_RULES_DIR, { recursive: true });
     }
-    // Copy CLAUDE.md template
-    (0, templates_1.copyTemplateFile)('CLAUDE.md', platform_1.CLAUDE_MD);
+    // Deploy to rules/ekkos.md (safe to overwrite — this is our file)
+    (0, templates_1.copyTemplateFile)('CLAUDE.md', platform_1.CLAUDE_EKKOS_RULES);
 }
 /**
- * Check if CLAUDE.md is deployed
+ * Check if ekkOS instructions are deployed
  */
 function isInstructionsDeployed() {
-    return (0, fs_1.existsSync)(platform_1.CLAUDE_MD);
+    return (0, fs_1.existsSync)(platform_1.CLAUDE_EKKOS_RULES);
 }
 /**
  * Get the CLAUDE.md content (for preview)

package/dist/index.js

@@ -42,13 +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 usage_1 = require("./commands/usage");
+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"));
@@ -59,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')
@@ -92,6 +248,9 @@ commander_1.program
     .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,
@@ -101,7 +260,24 @@ commander_1.program
         noInject: options.skipInject,
         research: options.research,
         noDna: options.skipDna,
-        noProxy: options.skipProxy
+        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
@@ -174,22 +350,10 @@ hooksCmd
     .action((options) => {
     (0, hooks_1.hooksStatus)({ verbose: options.verbose });
 });
-// Usage command - track session token usage
-commander_1.program
-    .command('usage [session-id]')
-    .description('Track Claude Code session token usage and context percentage')
-    .option('--instance <id>', 'Instance ID (project path identifier)')
-    .option('--list', 'List available sessions')
-    .action((sessionId, options) => {
-    const args = [];
-    if (sessionId)
-        args.push(sessionId);
-    if (options.instance)
-        args.push('--instance', options.instance);
-    if (options.list)
-        args.push('--list');
-    (0, usage_1.usageCommand)(args);
-});
+// 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')
@@ -222,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')
@@ -311,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 {};