Configuration

Config file

Location: ~/.codika-os/config.json. Mode 0600 (owner read/write only). Owned by codika-os — don’t hand-edit unless you know what you’re doing; use codika-os config set instead.

Shape:

{
  "activeProfile": "codika",
  "profiles": {
    "codika": {
      "email": "you@codika.io",
      "organization": "Codika",
      "apiKey": "cos_xxxx...",
      "apiBaseUrl": "https://os.codika.io"
    },
    "dev-local": {
      "email": "you@codika.io",
      "organization": "Codika",
      "apiKey": "cos_yyyy...",
      "apiBaseUrl": "http://localhost:5190"
    }
  }
}

Resolution chain

When a command needs a key or base URL, it checks in order:

1. The --profile <name> flag, if given.
2. The matching env var (CODIKA_OS_API_KEY, CODIKA_OS_API_BASE_URL).
3. The activeProfile in the config file.

Env vars are useful for CI:

export CODIKA_OS_API_KEY=cos_xxxx...
export CODIKA_OS_API_BASE_URL=https://os.codika.io
codika-os sync --json

Other state files

Path	Purpose
~/.codika-os/events.db	Local SQLite event store. WAL mode. Hooks append, aggregator reads.
~/.codika-os/last-sync	Timestamp of the most recent successful sync. Used by sync --if-stale and by the SessionStart hook to decide whether to trigger a background sync (>20h threshold).
~/.codika-os/sync.lock	Single-writer lockfile (atomic mkdir). Prevents concurrent background syncs when multiple Claude Code sessions start at once. Stale locks are cleaned up by the next sync.
~/.claude/settings.json	Contains the five hook entries written by codika-os install.

Hook entries

codika-os install writes (idempotently) into ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart":     [{ "command": "codika-os hooks SessionStart" }],
    "UserPromptSubmit": [{ "command": "codika-os hooks UserPromptSubmit" }],
    "Stop":             [{ "command": "codika-os hooks Stop" }],
    "SessionEnd":       [{ "command": "codika-os hooks SessionEnd" }],
    "PostToolUse":      [{ "command": "codika-os hooks PostToolUse" }]
  }
}

If Claude Code already has hooks configured for these events, install merges rather than overwriting.

The SessionStart handler does two things: append one row to local SQLite (like every other hook), and — if ~/.codika-os/last-sync is older than 20 hours — fire codika-os sync --if-stale --json as a detached background subprocess. The hook itself returns in under 50 ms; the background sync runs without blocking the agent. A lockfile (~/.codika-os/sync.lock) ensures only one sync runs at a time even if several Claude Code sessions start within seconds of each other.

Source

Implementation: codika-os-cli/src/utils/config.ts, codika-os-cli/src/cli/commands/install.ts, codika-os-cli/src/cli/commands/hooks/session-start.ts.