Overview

The codika-os CLI is the canonical interface to the tracking system. Every operation — install, sync, status, auth — is a CLI command. The plugin skills shell out to these commands with --json and parse the results.

When to use the CLI directly vs the plugin

Context	Use
Inside a Claude Code (or any Open-Plugin) conversation	The plugin skills (/codika-os:<skill>)
Shell scripts, CI, manual investigation	The CLI directly
Both are an option	The plugin — the CLI command shows up in the skill’s output anyway

What you get

• Local capture via five Claude Code hooks → ~/.codika-os/events.db.
• Aggregation of local SQLite + Claude Code JSONL transcripts at sync time.
• Project classification (longest-prefix path match against project_path_prefixes; agent-inline fallback via /codika-os:classify-sessions for whatever the path classifier can’t decide).
• Sync to the codika-os-app dashboard via POST /api/sync.
• Background sync triggered by the Claude Code SessionStart hook when last-sync is older than 20h. No system cron is involved.

Conventions

• --json on every read/admin command. Stable shape: { success: true, data } or { success: false, error: { code, message, nextAction? } }.
• Profiles in ~/.codika-os/config.json. Switch with codika-os use <name>.
• API keys prefixed cos_, sent as Authorization: Bearer <key>. The CLI handles the header.
• nextAction on every auth … error payload — a short imperative string designed to be acted on programmatically by an agent. Surface it to the user verbatim.

Source of truth

The CLI source is in codika-os-cli:

• Commands: src/cli/commands/
• Hook scripts: src/cli/commands/hooks/
• Core (classifier, aggregator, uploader, human-time, jsonl-parser): src/core/
• Config: src/utils/config.ts

Next

• Installation — npm install -g codika-os.
• Auth — OTP signup and login.
• Commands — every command and flag.
• Configuration — config file, env vars, hook entries.