@ekkos/cli 1.3.9 → 1.4.1

package/dist/index.js

@@ -38,15 +38,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-// The `run` command is the default (bare `ekkos`), so it stays eager.
-// `dashboardCommand` is eager because `run --dashboard` spawns `ekkos dashboard` in tmux.
-// All other command modules are loaded lazily inside .action() callbacks.
-const run_1 = require("./commands/run");
-const dashboard_1 = require("./commands/dashboard");
+// Command modules loaded lazily inside .action() callbacks to avoid
+// importing most heavy modules (node-pty, swarm, etc.) on every launch.
+// Commands that must work in subprocess mode (usage/dashboard) are registered eagerly.
 const chalk_1 = __importDefault(require("chalk"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const index_1 = require("./commands/usage/index");
+const dashboard_1 = require("./commands/dashboard");
 // Get version from package.json (CommonJS compatible)
 const pkgPath = path.resolve(__dirname, '../package.json');
 const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
@@ -63,16 +63,13 @@ commander_1.program
     .addHelpText('after', [
     '',
     chalk_1.default.cyan.bold('Examples:'),
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Launch Claude Code with ekkOS memory (default)')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos pulse')}                        ${chalk_1.default.gray('Launch ekkOS Pulse preset: bypass + selector + live dashboard')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos --model')}                      ${chalk_1.default.gray('Open Claude launch selector (model + context + resume)')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos gemini')}                       ${chalk_1.default.gray('Launch Gemini CLI with ekkOS memory')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Claude Code with live usage dashboard')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos init')}                         ${chalk_1.default.gray('First-time setup — authenticate + configure IDEs')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep ekkOS_CONTEXT.md files updated on disk')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Store your Gemini API key in the cloud')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos swarm launch -t "task"')}       ${chalk_1.default.gray('Parallel workers on a decomposed task')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Start Claude Code with ekkOS memory (default)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos codex')}                        ${chalk_1.default.gray('Start Codex (OpenAI) mode')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos daemon start')}                 ${chalk_1.default.gray('Start the background mobile sync service')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep local ekkOS_CONTEXT.md files updated on disk')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Securely store your Gemini API key in the cloud')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent in a directory')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch Claude with live usage dashboard')}`,
     '',
     chalk_1.default.gray('  Run ') + chalk_1.default.white('ekkos <command> --help') + chalk_1.default.gray(' for detailed options on any command.'),
     '',
@@ -137,53 +134,52 @@ commander_1.program
         }
         const groups = [
             {
-                title: 'Launch',
-                icon: '🚀',
+                title: 'Getting Started',
+                icon: '▸',
                 commands: [
-                    { name: 'run', desc: 'Claude Code with memory, proxy, and mobile sync', note: 'default' },
-                    { name: 'pulse', desc: 'Pulse preset: bypass + guided selector + live dashboard' },
-                    { name: 'gemini', desc: 'Gemini CLI with memory and proxy' },
-                    { name: 'codex', desc: 'Codex (OpenAI) with mobile sync' },
-                    { name: 'acp', desc: 'Any ACP-compatible agent' },
+                    { name: 'init', desc: 'First-time setup — authenticate and configure IDEs' },
+                    { name: 'scan', desc: 'Scan repo structure and seed ekkOS system registry' },
+                    { name: 'docs', desc: 'Cortex: Watch and regenerate local ekkOS_CONTEXT.md files' },
+                    { name: 'status', desc: 'Show overall system status (Memory, Sync Daemon, Auth)' },
+                    { name: 'doctor', desc: 'Check system prerequisites and fix runaway processes' },
                 ],
             },
             {
-                title: 'Setup',
-                icon: '⚙️',
+                title: 'Launch Agents (Local + Mobile Synced)',
+                icon: '▸',
                 commands: [
-                    { name: 'init', desc: 'Authenticate and configure IDEs' },
-                    { name: 'scan', desc: 'Discover repo structure and seed system registry' },
-                    { name: 'docs', desc: 'Watch and regenerate ekkOS_CONTEXT.md files' },
-                    { name: 'connect', desc: 'Store AI vendor API keys in the cloud' },
+                    { name: 'run', desc: 'Launch Claude Code with memory and mobile control', note: 'default' },
+                    { name: 'codex', desc: 'Launch Codex (OpenAI) with mobile control' },
+                    { name: 'gemini', desc: 'Launch Gemini mode (ACP) with mobile control' },
+                    { name: 'acp', desc: 'Launch a generic ACP-compatible agent' },
                 ],
             },
             {
-                title: 'Agents & Swarm',
-                icon: '🐝',
+                title: 'Mobile Sync & Cloud (Synk)',
+                icon: '▸',
                 commands: [
-                    { name: 'agent', desc: 'Manage headless agents (create, list, stop)' },
-                    { name: 'swarm', desc: 'Parallel workers with Q-learning routing' },
-                    { name: 'sandbox', desc: 'OS-level sandboxing for agent execution' },
+                    { name: 'daemon', desc: 'Manage background mobile sync service (start, stop, status)' },
+                    { name: 'connect', desc: 'Securely store AI vendor API keys in the cloud' },
+                    { name: 'sandbox', desc: 'Configure OS-level sandboxing for agent execution' },
+                    { name: 'notify', desc: 'Send push notifications to your Synk mobile app' },
                 ],
             },
             {
-                title: 'Monitor',
-                icon: '📊',
+                title: 'Headless Agents (Remote Control)',
+                icon: '▸',
                 commands: [
-                    { name: 'status', desc: 'System status (Memory, Sync, Auth)' },
-                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
-                    { name: 'usage', desc: 'Token usage and cost tracking' },
-                    { name: 'sessions', desc: 'List active local CLI sessions' },
+                    { name: 'agent', desc: 'Manage remote headless agents (create, list, stop)' },
+                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, and swarm dashboard' },
                 ],
             },
             {
-                title: 'Utilities',
-                icon: '🔧',
+                title: 'Monitoring & Usage',
+                icon: '▸',
                 commands: [
-                    { name: 'auth', desc: 'Manage authentication tokens' },
-                    { name: 'daemon', desc: 'Background mobile sync service (start, stop)' },
-                    { name: 'notify', desc: 'Push notifications to Synk mobile app' },
-                    { name: 'doctor', desc: 'Check prerequisites and fix issues' },
+                    { name: 'auth', desc: 'Manage authentication for Memory, Agents, and Mobile App' },
+                    { name: 'usage', desc: 'Token usage and cost tracking (daily, weekly, monthly, session)' },
+                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
+                    { name: 'sessions', desc: 'List active local CLI sessions' },
                 ],
             },
         ];
@@ -241,13 +237,28 @@ commander_1.program
         path: options.path,
     });
 });
-// Local living docs command
+// ekkOS Cortex command group
 const docsCmd = commander_1.program
     .command('docs')
-    .description('Manage local ekkOS_CONTEXT.md living docs');
+    .alias('cortex')
+    .description('ekkOS Cortex: Manage local living docs (ekkOS_CONTEXT.md)');
+docsCmd
+    .command('init')
+    .description('Initialize Cortex: Discover systems and perform a one-shot generation of all ekkOS_CONTEXT.md files')
+    .option('-p, --path <path>', 'Path to repository root (default: current directory)')
+    .option('--timezone <iana-tz>', 'IANA timezone for timestamps (default: local machine timezone)')
+    .option('--no-seed', 'Do not seed the platform registry')
+    .action(async (options) => {
+    const { initLivingDocs } = await Promise.resolve().then(() => __importStar(require('./commands/init-living-docs')));
+    await initLivingDocs({
+        path: options.path,
+        timeZone: options.timezone,
+        noSeed: options.seed === false,
+    });
+});
 docsCmd
     .command('watch')
-    .description('Watch the local workspace and keep ekkOS_CONTEXT.md files current on disk')
+    .description('Watch the local workspace and keep Cortex docs current on disk')
     .option('-p, --path <path>', 'Path to watch (default: current directory)')
     .option('--timezone <iana-tz>', 'IANA timezone for timestamps (default: local machine timezone)')
     .option('--poll-interval-ms <ms>', 'Polling interval fallback in milliseconds', (value) => parseInt(value, 10))
@@ -263,6 +274,30 @@ docsCmd
         noSeed: options.seed === false,
     });
 });
+docsCmd
+    .command('setup-ci')
+    .description('Generate a GitHub Actions workflow to automatically validate Cortex docs on PRs')
+    .option('-p, --path <path>', 'Path to repository root (default: current directory)')
+    .action(async (options) => {
+    const { setupCiCommand } = await Promise.resolve().then(() => __importStar(require('./commands/setup-ci')));
+    const exitCode = await setupCiCommand({ repoRoot: options.path || process.cwd() });
+    process.exit(exitCode);
+});
+docsCmd
+    .command('validate')
+    .description('Validate Cortex docs (ekkOS_CONTEXT.md) in a repository (CI/CD friendly)')
+    .option('-p, --path <path>', 'Path to repository root (default: current directory)')
+    .option('--fix', 'Attempt to automatically fix content hash mismatches')
+    .option('--system <system_id>', 'Filter validation to a specific system_id')
+    .action(async (options) => {
+    const { validateLivingDocsCommand } = await Promise.resolve().then(() => __importStar(require('./commands/validate-living-docs')));
+    const exitCode = await validateLivingDocsCommand({
+        repoRoot: options.path || process.cwd(),
+        fix: options.fix,
+        systemFilter: options.system,
+    });
+    process.exit(exitCode);
+});
 // Status command
 commander_1.program
     .command('status')
@@ -324,6 +359,10 @@ commander_1.program
     .description('Launch Claude Code with ekkOS memory proxy (IPC compression + pattern injection)')
     .option('-s, --session <name>', 'Session name to restore on clear')
     .option('-b, --bypass', 'Enable bypass permissions mode (dangerously skip all permission checks)')
+    .option('--model [model]', 'Launch model: pass a model ID, or omit value to open the interactive selector')
+    .option('--context-window <window>', 'Context lane override: auto, 200k, or 1m')
+    .option('--continue-last', 'Continue most recent Claude conversation')
+    .option('--resume-session <id>', 'Resume Claude conversation by ID')
     .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)')
@@ -331,12 +370,9 @@ commander_1.program
     .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('--add-dir <dirs...>', 'Additional directories Claude Code can access (outside working directory)')
-    .option('--model [model]', 'Claude launch model. Pass without a value to open the launch selector')
-    .option('--context-window <mode>', 'Context window mode: auto, 200k, or 1m')
-    .option('--continue-last', 'Continue the most recent Claude conversation')
-    .option('--resume-session <id>', 'Resume a Claude conversation by session ID')
-    .action((options) => {
-    (0, run_1.run)({
+    .action(async (options) => {
+    const { run } = await Promise.resolve().then(() => __importStar(require('./commands/run')));
+    run({
         session: options.session,
         bypass: options.bypass,
         verbose: options.verbose,
@@ -354,32 +390,27 @@ commander_1.program
 });
 commander_1.program
     .command('pulse')
-    .description('Launch ekkOS Pulse: bypass + selector + live Claude dashboard')
+    .description('Launch PULSE mode (equivalent to `ekkos -b --model --dashboard`)')
     .option('-s, --session <name>', 'Session name to restore on clear')
-    .option('--no-bypass', 'Disable bypass permissions mode')
+    .option('--context-window <window>', 'Context lane override: auto, 200k, or 1m')
+    .option('--continue-last', 'Continue most recent Claude conversation')
+    .option('--resume-session <id>', 'Resume Claude conversation by ID')
     .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('--skip-inject', 'Monitor-only mode (detect context wall but print instructions instead of auto-inject)')
     .option('--skip-proxy', 'Skip API proxy (use direct Anthropic API, disables seamless context eviction)')
     .option('--add-dir <dirs...>', 'Additional directories Claude Code can access (outside working directory)')
-    .option('--model [model]', 'Claude launch model. Omit the value to open the launch selector (default for pulse)')
-    .option('--context-window <mode>', 'Context window mode: auto, 200k, or 1m')
-    .option('--continue-last', 'Continue the most recent Claude conversation')
-    .option('--resume-session <id>', 'Resume a Claude conversation by session ID')
-    .action((options) => {
-    (0, run_1.run)({
+    .action(async (options) => {
+    const { run } = await Promise.resolve().then(() => __importStar(require('./commands/run')));
+    run({
         session: options.session,
-        bypass: options.bypass !== false,
+        bypass: true,
         pulse: true,
         verbose: options.verbose,
-        doctor: options.doctor,
         noInject: options.skipInject,
-        research: options.research,
         noProxy: options.skipProxy,
         dashboard: true,
         addDirs: options.addDir,
-        model: options.model ?? true,
+        model: true,
         contextWindow: options.contextWindow,
         continueLast: options.continueLast,
         resumeSession: options.resumeSession,
@@ -392,12 +423,14 @@ commander_1.program
     .option('-s, --session <name>', 'Session name')
     .option('-v, --verbose', 'Show debug output')
     .option('--skip-proxy', 'Skip API proxy (use direct Gemini API)')
+    .option('--dashboard', 'Launch Gemini with a dedicated live dashboard split (requires tmux)')
     .action(async (options) => {
     const { gemini } = await Promise.resolve().then(() => __importStar(require('./commands/gemini')));
     gemini({
         session: options.session,
         verbose: options.verbose,
         noProxy: options.skipProxy,
+        dashboard: options.dashboard,
     });
 });
 // Test Claude — bare proxy test (no CLI wrapper)
@@ -465,19 +498,9 @@ commander_1.program
     console.log(chalk_1.default.gray('  the ekkOS proxy — no shell hooks required.'));
     console.log('');
 });
-// Usage command — lightweight stub, heavy handler loaded lazily
-commander_1.program
-    .command('usage')
-    .description('Token usage and cost tracking (daily, weekly, monthly, session)')
-    .allowUnknownOption()
-    .action(async () => {
-    const { registerUsageCommand } = await Promise.resolve().then(() => __importStar(require('./commands/usage/index')));
-    const { Command } = await Promise.resolve().then(() => __importStar(require('commander')));
-    const usageProgram = new Command('ekkos');
-    registerUsageCommand(usageProgram);
-    usageProgram.parse(['node', 'ekkos', 'usage', ...process.argv.slice(3)]);
-});
-// Dashboard command — eager because `run --dashboard` spawns `ekkos dashboard` in tmux
+// Usage and dashboard are registered synchronously so command parsing is reliable
+// when launched as subprocesses (for example tmux split-pane dashboard mode).
+(0, index_1.registerUsageCommand)(commander_1.program);
 commander_1.program.addCommand(dashboard_1.dashboardCommand);
 // Sessions command - list active Claude Code sessions (swarm support)
 commander_1.program
@@ -563,6 +586,7 @@ swarmCmd
     .option('--queen-strategy <strategy>', 'Queen strategy (adaptive-default, hierarchical-cascade, mesh-consensus)')
     .option('-v, --verbose', 'Show debug output')
     .action(async (options) => {
+    // Auto-open wizard when --task is missing
     if (!options.task) {
         const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup')));
         swarmSetup();
@@ -582,7 +606,10 @@ swarmCmd
 swarmCmd
     .command('setup')
     .description('Interactive TUI wizard for configuring and launching a swarm')
-    .action(async () => { const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup'))); swarmSetup(); });
+    .action(async () => {
+    const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup')));
+    swarmSetup();
+});
 swarmCmd
     .command('swarm-dashboard')
     .description('Live swarm dashboard')

package/dist/utils/state.d.ts

@@ -3,7 +3,20 @@ export declare const STATE_FILE: string;
 export declare const ACTIVE_SESSIONS_FILE: string;
 export declare const AUTO_CLEAR_FLAG: string;
 export declare const CONFIG_FILE: string;
-export interface ActiveSession {
+export interface ClaudeSessionMetadata {
+    provider?: 'claude' | 'gemini';
+    claudeModel?: string;
+    claudeLaunchModel?: string;
+    claudeProfile?: string;
+    claudeContextWindow?: 'auto' | '200k' | '1m';
+    claudeContextSize?: number;
+    claudeMaxOutputTokens?: number;
+    claudeCodeVersion?: string;
+    geminiProjectId?: string;
+    dashboardEnabled?: boolean;
+    bypassEnabled?: boolean;
+}
+export interface ActiveSession extends ClaudeSessionMetadata {
     sessionId: string;
     sessionName: string;
     pid: number;
@@ -82,7 +95,7 @@ export declare function getActiveSessions(): ActiveSession[];
 /**
  * Register a new active session (for swarm tracking)
  */
-export declare function registerActiveSession(sessionId: string, sessionName: string, projectPath: string): ActiveSession;
+export declare function registerActiveSession(sessionId: string, sessionName: string, projectPath: string, metadata?: ClaudeSessionMetadata): ActiveSession;
 /**
  * Update heartbeat for current process's session
  */
@@ -103,4 +116,4 @@ export declare function getActiveSessionByName(sessionName: string): ActiveSessi
  * Update the session for the current PID (when session name is detected)
  * This does NOT write to the global state.json - only to active-sessions.json
  */
-export declare function updateCurrentProcessSession(sessionId: string, sessionName: string): void;
+export declare function updateCurrentProcessSession(sessionId: string, sessionName: string, metadata?: Partial<ClaudeSessionMetadata>): void;

package/dist/utils/state.js

@@ -286,7 +286,7 @@ function getActiveSessions() {
 /**
  * Register a new active session (for swarm tracking)
  */
-function registerActiveSession(sessionId, sessionName, projectPath) {
+function registerActiveSession(sessionId, sessionName, projectPath, metadata) {
     ensureEkkosDir();
     const sessions = getActiveSessions();
     const now = new Date().toISOString();
@@ -299,7 +299,8 @@ function registerActiveSession(sessionId, sessionName, projectPath) {
         pid,
         startedAt: now,
         projectPath,
-        lastHeartbeat: now
+        lastHeartbeat: now,
+        ...metadata,
     };
     filtered.push(newSession);
     fs.writeFileSync(exports.ACTIVE_SESSIONS_FILE, JSON.stringify(filtered, null, 2));
@@ -371,7 +372,7 @@ function isProcessAlive(pid) {
  * Update the session for the current PID (when session name is detected)
  * This does NOT write to the global state.json - only to active-sessions.json
  */
-function updateCurrentProcessSession(sessionId, sessionName) {
+function updateCurrentProcessSession(sessionId, sessionName, metadata) {
     try {
         const sessions = getActiveSessions();
         const pid = process.pid;
@@ -379,6 +380,12 @@ function updateCurrentProcessSession(sessionId, sessionName) {
         if (idx !== -1) {
             sessions[idx].sessionId = sessionId;
             sessions[idx].sessionName = sessionName;
+            if (metadata) {
+                sessions[idx] = {
+                    ...sessions[idx],
+                    ...metadata,
+                };
+            }
             sessions[idx].lastHeartbeat = new Date().toISOString();
             fs.writeFileSync(exports.ACTIVE_SESSIONS_FILE, JSON.stringify(sessions, null, 2));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekkos/cli",
-  "version": "1.3.9",
+  "version": "1.4.1",
   "description": "ekkOS memory CLI — persistent memory for AI coding assistants (Claude Code, Gemini, Cursor, Windsurf)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",