Skip to content
codika-os

Quickstart

By the end of this page your Claude Code sessions are captured, classified, and visible on the dashboard at /tracking.

Prerequisites

Section titled “Prerequisites”
  • Node.js 20+ (node --version to check)
  • Any OS that runs Claude Code — sync is triggered by a Claude Code SessionStart hook, not a system cron
  • A @codika.io email — non-Codika emails are rejected with 403
  • Claude Code installed and signed in

No codika-os account yet? That’s fine. Step 3 creates one.

Step 1 — Add the plugin marketplace

Section titled “Step 1 — Add the plugin marketplace”
/plugin marketplace add codika-io/codika-os-plugin

For Open-Plugin-compatible hosts other than Claude Code (Cursor, etc.), skip steps 1–2 and run npx plugins add codika-io/codika-os-plugin instead.

Step 2 — Install the plugin

Section titled “Step 2 — Install the plugin”
/plugin install codika-os@codika-os-plugin

Ten skills are now available under /codika-os:*. The one you need first is setup-codika-os.

Step 3 — Run setup

Section titled “Step 3 — Run setup”
/codika-os:setup-codika-os

The skill does, in order:

  1. npm install -g codika-os
  2. Asks for your @codika.io email.
  3. Runs codika-os auth signup-request --email you@codika.io (or login-request if you already have an account).
  4. Prompts you for the 6-digit code emailed to you.
  5. Runs codika-os auth signup-complete --email you@codika.io --code 123456.
  6. Runs codika-os install — registers the five Claude Code hooks in ~/.claude/settings.json and creates ~/.codika-os/events.db. No system cron is installed; the SessionStart hook is what fires codika-os sync in the background when last-sync is older than 20h.

codika-os has no organization concept — your API key is owned by your worker email. If login returns no_dashboard_access, the email isn’t yet authorized in PROD’s dashboard_access table; ask an admin to invite you, then retry.

Your cos_… key is stored at ~/.codika-os/config.json (mode 0600) and set as the active profile.

Step 4 — Start a Claude Code session

Section titled “Step 4 — Start a Claude Code session”

Just use Claude Code normally. The five hooks (SessionStart, UserPromptSubmit, Stop, SessionEnd, PostToolUse) fire automatically and append one row of metadata to local SQLite per event. They complete in under 50 ms and never make network calls.

Step 5 — Force a sync (optional)

Section titled “Step 5 — Force a sync (optional)”
/codika-os:sync-codika-os

The SessionStart hook will fire codika-os sync automatically the next time you open a Claude Code session (if last-sync is >20h old). To see your activity on the dashboard right now, invoke the skill or run codika-os sync directly. It parses local SQLite + ~/.claude/projects/*.jsonl, runs the deterministic path classifier, computes leverage, and uploads to /api/sync. Sessions the path classifier can’t attribute are uploaded with project_id = NULL.

Step 7 — Classify the residual (if any)

Section titled “Step 7 — Classify the residual (if any)”

If sync reports summary.unattributed > 0, run:

/codika-os:classify-sessions

The skill walks the backlog month by month and asks the current Claude Code agent to attribute each pending session in-context (no claude -p subprocess, no extra cost beyond what the operator’s own subscription already covers). See Classification for the full model.

Step 6 — Open the dashboard

Section titled “Step 6 — Open the dashboard”

Once codika-os-app is running locally (or once the prod deployment is set up), open http://localhost:5190/tracking. You’ll see:

  • Donut KPIs — total human time, agent time, leverage, cost — grouped by category for the period.
  • Per-project table — breakdown by client, product, tool, platform area, growth motion, and knowledge.
  • Drill-downs — per-project and per-session pages with classification details (project, category, subcategory).

CLI-direct path (no plugin)

Section titled “CLI-direct path (no plugin)”

If you can’t use the plugin (running the CLI from a non-agent shell, scripting in CI, etc.):

Terminal window
npm install -g codika-os
codika-os --version


codika-os auth signup-request --email you@codika.io
# check email for code
codika-os auth signup-complete --email you@codika.io --code 123456


codika-os install
codika-os sync
codika-os status

The plugin path and the CLI-direct path are functionally identical — the plugin is just the ergonomic wrapper for use inside an agent conversation.

Next steps

Section titled “Next steps”