ekkOS Documentation

CLI Reference

The ekkos CLI manages your memory-enhanced development environment. 15 commands across 5 categories.

Installation

npm install -g @ekkos/cli

Requires Node.js 18 or later. After installing, run ekkos init to authenticate and configure your environment.

Quick Start

Install

npm install -g @ekkos/cli

Initialize

ekkos init

Authenticate, select IDEs, and deploy configuration

Run

ekkos

Launch Claude Code with persistent memory. That's it.

All Commands

Getting Started

Install and configure ekkOS for the first time.

ekkos

The default command. Just typing ekkos starts Claude Code with ekkOS memory — no subcommand needed. Equivalent to ekkos run.

Usage

ekkos

Example Output

$ ekkos

  ╔══════════════════════════════════════╗
  ║  ekkOS_Pulse v1.1.9                 ║
  ╚══════════════════════════════════════╝
  Session: bright-falcon-soars
  Memory:  connected (68 tools)

  Launching Claude Code...

ekkos init

Interactive setup wizard. Authenticates via device code flow (opens your browser), detects installed IDEs, and configures the MCP server, hooks, skills, agents, plugins, and CLAUDE.md.

Usage

ekkos init [options]

Options

-i, --ide <ide>IDE to set up (claude, cursor, windsurf, all)

-k, --key <key>Use API key instead of device auth (skip browser)

-f, --forceForce re-authentication and overwrite existing config

--skip-hooksSkip hook deployment

--skip-skillsSkip skills deployment

Example Output

$ ekkos init

  🧠 ekkOS Memory Setup
  ─────────────────────

  → Opening browser for authentication...
  → Device code: ABCD-1234
  ✓ Authenticated as user@example.com (Pro tier)

  Select IDEs to configure:
    ☑ Claude Code
    ☑ Cursor
    ☐ Windsurf

  Deploying configuration...
    ✓ MCP server configured       (~/.claude.json)
    ✓ Hooks installed              (~/.claude/hooks/)
    ✓ Settings registered          (~/.claude/settings.json)
    ✓ Skills deployed              (~/.claude/skills/)
    ✓ Agents registered            (~/.claude/agents/)
    ✓ Plugins installed            (~/.claude/plugins/ekkos/)
    ✓ CLAUDE.md deployed           (~/.claude/CLAUDE.md)

  Verifying deployment...
    ✓ All 7 components verified

  ┌──────────────────────────────────┐
  │  ✓ ekkOS is ready!              │
  │  Next step: ekkos run           │
  └──────────────────────────────────┘

Running

Launch Claude Code with ekkOS memory enhancements.

ekkos run

Start Claude Code with ekkOS memory. This is the default command — also triggered by just typing ekkos. Routes all API calls through the ekkOS proxy for context management, generates a unique 3-word session name, and fires hooks on every turn to capture memory.

Usage

ekkos run [options]

Options

-s, --session <name>Session name to restore on clear

-b, --bypassEnable bypass permissions mode (skip all permission checks)

-v, --verboseShow debug output

-d, --doctorRun diagnostics before starting

-r, --researchAuto-run research agent on startup

--skip-injectMonitor-only mode

--skip-dnaSkip ccDNA injection

--skip-proxySkip API proxy (use direct Anthropic API)

--dashboardLaunch with live usage dashboard in tmux split

--add-dir <dirs...>Additional directories Claude Code can access

Example Output

$ ekkos run --bypass --verbose

  ╔══════════════════════════════════════╗
  ║  ekkOS_Pulse v1.1.9                 ║
  ╚══════════════════════════════════════╝
  Session: cosmic-penguin-runs
  Proxy:   proxy.ekkos.dev ✓
  Memory:  connected (68 tools)
  Bypass:  enabled

  Launching Claude Code...

ekkos test-claude

Launch Claude Code with proxy only — no ccDNA, no session binding, no injections. Useful for debugging whether an issue is in ekkOS or in Claude Code itself.

Usage

ekkos test-claude [options]

Options

--no-proxySkip proxy too (completely vanilla Claude)

--no-hooksTemporarily disable all hooks

-v, --verboseShow debug output

Example Output

$ ekkos test-claude --no-hooks

  🧪 Test Mode
  ─────────────
  Proxy:  proxy.ekkos.dev ✓
  ccDNA:  skipped
  Hooks:  disabled
  Session: disabled

  Launching vanilla Claude Code with proxy...

Monitoring

Check system health, view usage, and track sessions.

ekkos doctor

System health checker. Verifies environment prerequisites including Node.js version, Claude Code installation, session support, hook integrity, and MCP configuration.

Usage

ekkos doctor [options]

Options

-f, --fixAttempt safe auto-fixes and show commands for manual fixes

-j, --jsonOutput machine-readable JSON report

Example Output

$ ekkos doctor

  🩺 ekkOS Doctor
  ─────────────────────

  ✓ PASS  Node.js >= 18 (v22.2.0)
  ✓ PASS  Claude Code installed (v2.1.6)
  ✓ PASS  Session binding available
  ✓ PASS  Hooks verified (6/6 checksums match)
  ✓ PASS  MCP configuration valid
  ⚠ WARN  ccDNA not installed (optional)

  Result: Ready to run

ekkos status

Shows your ekkOS memory statistics and installation info — pattern count, directive count, episodes captured, and account tier.

Usage

ekkos status

Example Output

$ ekkos status

  📊 ekkOS Memory Status
  ──────────────────────────

  Account:    user@example.com (Pro)
  Patterns:   247 active, 12 quarantined
  Directives: 34 rules
  Episodes:   1,203 captured
  Secrets:    8 stored

ekkos test

Tests connection to the ekkOS memory API. Runs four checks: API health, pattern query, memory capture endpoint, and IDE configuration verification.

Usage

ekkos test

Example Output

$ ekkos test

  🔌 ekkOS Connection Test
  ────────────────────────────

  1. API health check        ✓ 200 OK (42ms)
  2. Pattern query            ✓ 247 patterns found
  3. Memory capture           ✓ Endpoint accepts writes
  4. IDE configuration        ✓ MCP server configured

  All tests passed.

ekkos usage

Token usage and cost tracking. View daily, weekly, monthly, or per-session breakdowns of your token consumption and costs.

Usage

ekkos usage <daily|weekly|monthly|session>

Subcommands

dailyToday's usage

weeklyThis week's usage

monthlyThis month's usage

sessionCurrent session usage

Example Output

$ ekkos usage daily

  📈 Usage — Today (Feb 21, 2026)
  ────────────────────────────────

  Input tokens:   1,247,832
  Output tokens:  312,456
  Cache reads:    943,211
  Cache writes:   304,621
  Estimated cost: $4.72

  Sessions: 3 active

ekkos dashboard

Live TUI dashboard for real-time session monitoring. Shows token usage, cache hit rates, memory operations, and session timeline in your terminal.

Usage

ekkos dashboard

Example Output

$ ekkos dashboard

  ┌─ ekkOS Dashboard ──────────────────────┐
  │                                         │
  │  Session: cosmic-penguin-runs           │
  │  Uptime:  1h 23m                        │
  │  Turns:   47                            │
  │                                         │
  │  Tokens   ████████████░░░░  72%         │
  │  Cache    ██████████████░░  89% hits    │
  │  Memory   ██████░░░░░░░░░░  38% used    │
  │                                         │
  └─────────────────────────────────────────┘

ekkos sessions

List active Claude Code sessions. Useful for multi-session and swarm workflows where multiple instances run in parallel.

Usage

ekkos sessions [options]

Options

-j, --jsonOutput machine-readable JSON

Example Output

$ ekkos sessions

  🧵 Active Sessions
  ──────────────────────

  1. cosmic-penguin-runs   (1h 23m, 47 turns)
  2. bright-falcon-soars   (0h 12m, 8 turns)
  3. swift-river-flows     (0h 03m, 2 turns)

Configuration

Manage hooks, streams, and deployment artifacts.

ekkos hooks

Manage Claude Code hook installation. Hooks enable the Golden Loop — automatic memory capture and retrieval on every interaction.

Usage

ekkos hooks <install|verify|status>

Subcommands

installInstall hooks to ~/.claude/hooks/

verifyVerify hook checksums

statusShow hook enablement status

Example Output

$ ekkos hooks verify

  🔗 Hook Verification
  ──────────────────────────

  ✓ user-prompt-submit.sh  (checksum: OK)
  ✓ stop.sh                (checksum: OK)
  ✓ lib/contract.sh        (checksum: OK)

  All hooks verified.

ekkos stream

Stream capture management. View the status of real-time stream capture and list sessions that have stream data recorded.

Usage

ekkos stream <status|list>

Subcommands

statusShow capture status

listList sessions with stream data

Example Output

$ ekkos stream status

  📡 Stream Capture
  ──────────────────────

  Status:   active
  Session:  cosmic-penguin-runs
  Captured: 1,847 events
  Storage:  cloud (synced)

Advanced

Remote access, multi-agent swarms, and agent management.

ekkos setup-remote

Set up remote terminal access — run Claude Code on your PC and connect from anywhere. Pairs your machine with the ekkOS remote agent service.

Usage

ekkos setup-remote [options]

Options

-f, --forceForce re-pairing

--skip-serviceSkip installing background service

-v, --verboseShow detailed output

Example Output

$ ekkos setup-remote

  🌐 Remote Terminal Setup
  ─────────────────────────

  → Generating device pairing code...
  → Pair code: MEGA-BYTE-3947
  → Waiting for platform confirmation...
  ✓ Paired to account user@example.com

  → Installing background agent service...
  ✓ Agent service installed (launchd)
  ✓ Agent running on port 8377

  Remote access is ready.
  Connect at: platform.ekkos.dev/terminal

ekkos agent

Manage the remote terminal agent. The agent runs as a background service and maintains the connection between your local machine and the ekkOS platform.

Usage

ekkos agent <subcommand>

Subcommands

startStart the agent service

stopStop the agent service

restartRestart the agent service

statusCheck agent status

logsShow agent logs (-f to follow)

healthDiagnose connection issues

uninstallRemove agent and unpair

Example Output

$ ekkos agent status

  🤖 ekkOS Agent
  ────────────────────

  Status:     running
  PID:        48291
  Uptime:     3d 14h 22m
  Connection: WebSocket (healthy)
  Latency:    32ms
  Sessions:   2 active

ekkos swarm

Multi-agent parallel workers with Q-learning routing. Launch multiple Claude Code instances that work on subtasks in parallel, coordinated by a queen agent.

Usage

ekkos swarm <subcommand>

Subcommands

launch -t "task"Launch parallel workers for a task

setupInteractive TUI wizard for swarm configuration

statusQ-table stats and worker routing data

resetClear the Q-table

exportExport Q-table data

importImport Q-table data

dashboardSwarm monitoring TUI

Launch Options

-t, --task <task>Task description (required)

-w, --workers <count>Number of workers (2-8)

--no-bypassDisable bypass mode

--no-decomposeSkip AI task decomposition

--queen-strategy <strategy>Queen coordinator strategy

Example Output

$ ekkos swarm launch -t "Refactor auth module" -w 4

  🐝 ekkOS Swarm
  ────────────────────

  Task: "Refactor auth module"
  Strategy: queen-coordinated
  Workers: 4

  Decomposing task...
    → Worker 1: Extract auth middleware
    → Worker 2: Update token validation
    → Worker 3: Migrate session store
    → Worker 4: Update test suite

  Launching workers...
    ✓ Worker 1 started (swift-river-flows)
    ✓ Worker 2 started (bold-eagle-soars)
    ✓ Worker 3 started (calm-ocean-hums)
    ✓ Worker 4 started (keen-wolf-hunts)

  Queen coordinator active. Use 'ekkos swarm dashboard' to monitor.

How `ekkos run` Works

When you run ekkos, the CLI sets up a memory-enhanced environment around Claude Code. Here is the architecture:

CLI spawns Claude Code

The CLI sets ANTHROPIC_BASE_URL to point at proxy.ekkos.dev, then launches claude with session tracking. A unique 3-word session name is generated (e.g., "cosmic-penguin-runs").

API calls route through the ekkOS proxy

Every Anthropic API call passes through the proxy. In passthrough mode (default), messages are forwarded unmodified to maximize Anthropic's prompt cache hit rate. The proxy records token usage, session metadata, and turn timing.

Context eviction at ~80%

When the context window reaches approximately 80% capacity (~160K of 200K tokens), the proxy triggers intelligent eviction. With smart eviction enabled, the middle of the conversation is summarized while preserving the system prompt prefix and recent turns. Original messages are backed up for lossless recovery.

Hooks capture memory on every turn

Claude Code hooks fire at key lifecycle points (prompt submit, stop, pre-compact). These hooks capture conversation turns, trigger pattern retrieval, and preserve context before compaction — enabling the "Golden Loop" of search → apply → forge.

Session names are 3-word identifiers

Each session gets a deterministic human-readable name derived from its UUID (e.g., "cosmic-penguin-runs"). These names appear in the ekkOS footer, are used for memory retrieval, and make it easy to reference past sessions.

Architecture

┌─────────────────────────────────────────────────────────┐
│                      ekkos run                          │
│                                                         │
│  ┌─────────┐    ┌──────────────┐    ┌────────────────┐  │
│  │  Claude  │───▶│  ekkOS Proxy │───▶│   Anthropic    │  │
│  │  Code    │◀───│  (passthru)  │◀───│   API          │  │
│  └────┬─────┘    └──────┬───────┘    └────────────────┘  │
│       │                 │                                │
│       │ hooks           │ eviction / usage               │
│       ▼                 ▼                                │
│  ┌─────────┐    ┌──────────────┐    ┌────────────────┐  │
│  │  ekkOS  │    │   Smart      │    │   Cloud        │  │
│  │  Memory │    │   Eviction   │    │   Backup       │  │
│  │  API    │    │   (optional) │    │   (lossless)   │  │
│  └─────────┘    └──────────────┘    └────────────────┘  │
└─────────────────────────────────────────────────────────┘

Environment Variables

These environment variables control ekkOS behavior. Most are set automatically by ekkos init and ekkos run.

EKKOS_API_KEYrequired

Your ekkOS API key. Set automatically by ekkos init. Required for all API calls.

EKKOS_PROXY_MODE

Proxy routing mode. Set to "direct" to bypass the proxy and call Anthropic directly.

EKKOS_DISABLE_EVICTION

Set to "1" to disable context eviction entirely. Context will grow until the model limit.

EKKOS_SMART_EVICTION

Set to "1" to enable AI-powered intelligent context eviction instead of simple truncation.

EKKOS_DEBUG

Set to "1" for verbose debug logging from all ekkOS components.

Troubleshooting

"Not configured" error

Run ekkos init to set up your account and configuration. As of v1.1.8, ekkos run automatically redirects to init if no config exists.

Hooks out of date

Run ekkos hooks install to update hooks to the latest version, or re-run ekkos init --force to redeploy everything.

Doctor reports failures

Run ekkos doctor --fix for auto-fixes and specific remediation commands. Most issues are resolved by ensuring Node.js 18+ is installed and Claude Code is up to date.

Claude Code launches but memory is not working

Use ekkos test to verify API connectivity. If the API is healthy but memory tools are missing, check that your MCP server is configured in ~/.claude.json.

Proxy connection refused

If proxy.ekkos.dev is unreachable, use ekkos run --skip-proxy or ekkos test-claude --no-proxy to bypass the proxy and use the Anthropic API directly. Memory and hooks still work; only context eviction and usage tracking are skipped.

Platform-Specific Issues

🪟 ENOENT error on Windows

Windows users may see ENOENT errors if the shell cannot find the claude binary. Fix:

Install Claude Code globally: npm i -g @anthropic-ai/claude-code
Ensure your PATH includes the npm global bin directory
Try running from PowerShell (not Command Prompt)

Fixed in CLI v1.1.2

🪟 Session binding delayed on Windows

On some Windows setups, session binding may use a fallback mode. In this mode:

Session names start as "_pending" until the first hook fires
All memory features still work — only session naming is delayed
Using ekkos run gives the best experience

🐧 Headless Linux / SSH environments

ekkos init opens a browser for authentication by default. On headless servers:

Use ekkos init --key YOUR_API_KEY to skip browser auth entirely
Or copy ~/.ekkos/config.json from a machine where you already authenticated
Use ekkos setup-remote for remote terminal agent setup

🍎 macOS: Windsurf config path

Windsurf stores its MCP config at a different path than other IDEs: ~/.codeium/windsurf/mcp_config.json (not ~/.windsurf/). The CLI handles this automatically — just run ekkos init.

Session name stuck at "_pending"

In some environments, the session name may remain "_pending" until the first hook fires. This is expected behavior. Use ekkos run for full session name binding from startup.

Swarm workers not starting

Run ekkos swarm setup to configure your swarm environment first. Workers require Claude Code with bypass mode and sufficient API rate limits for parallel operation.

CLI Reference

Installation

Quick Start

Install

Initialize

Run

All Commands

Getting Started

Running

Monitoring

Configuration

Advanced

Getting Started

ekkos

Usage

Example Output

ekkos init

Usage

Options

Example Output

Running

ekkos run

Usage

Options

Example Output

ekkos test-claude

Usage

Options

Example Output

Monitoring

ekkos doctor

Usage

Options

Example Output

ekkos status

Usage

Example Output

ekkos test

Usage

Example Output

ekkos usage

Usage

Subcommands

Example Output

ekkos dashboard

Usage

Example Output

ekkos sessions

Usage

Options

Example Output

Configuration

ekkos hooks

Usage

Subcommands

Example Output

ekkos stream

Usage

Subcommands

Example Output

Advanced

ekkos setup-remote

Usage

Options

Example Output

ekkos agent

Usage

Subcommands

Example Output

ekkos swarm

Usage

Subcommands

Launch Options

Example Output

How ekkos run Works

CLI spawns Claude Code

API calls route through the ekkOS proxy

Context eviction at ~80%

Hooks capture memory on every turn

Session names are 3-word identifiers

How `ekkos run` Works