kodocodes

The Kodo CLI. Kodo turns the coding sessions you run with AI agents into a Recap: what you built, how, and at what cost. It reads the transcripts already on your disk, keeps metadata only, stores events in a local SQLite database, and syncs them idempotently to your account.

npm i -g kodocodes@latest && kodo daemon start
kodo today                 # what you and your agents did today
kodo recap last            # the Recap card for the most recent session

Needs Node 22.14 or newer. npm install runs nothing in the background; kodo daemon start scans every session already on your disk (once, with progress), then installs the daemon and starts it — now, at every login, and again on the new version within a minute of npm i -g kodocodes@latest. Prefer to look first? npx kodocodes scan backfills without installing anything, and asks once whether to keep it current. Nothing leaves your machine until you run kodo login.

• Plan and progress: https://github.com/usmangurowa/kodo/milestone/1
• Design: .ai/specs/active/kodo-cli.spec.md

Develop

pnpm install
pnpm -F kodocodes build          # dist/kodo.mjs
pnpm -F kodocodes kodo doctor    # runs bin/kodo.js against the bundle
pnpm -F kodocodes test

Point the CLI at a scratch home while developing so your real ~/.kodo stays untouched: KODO_HOME=/tmp/kodo pnpm -F kodocodes kodo scan.

Commands

| Command | Status | | ---------------------------------------------------- | ---------------------------------- | | kodo scan [--source] [--since] [--full] | works; readers land in #55 and #56 | | kodo doctor | works | | kodo config get\|set\|unset\|path | works | | kodo sessions, recap, today, stats, export | #57 | | kodo daemon … | #58 | | kodo login, logout, whoami, sync | #59 |

Global flags: --json, --no-color, --db <path>, --verbose. Exit codes: 0 ok, 1 user error, 2 environment, 3 sync.

Layout

bin/kodo.js          Node ≥ 22.14 check, silences the node:sqlite warning, loads dist/kodo.mjs
src/cli/             argv parsing, output, command registry, dispatcher
src/commands/        one file per command, exporting <name>Command
src/core/            errors + exit codes, hashing, ~/.kodo paths
src/config/          ~/.kodo/config.json (mode 0600)
src/store/           node:sqlite store and migrations
src/readers/         one folder per tool; _shared/ has JSONL slicing and helpers
src/scan/            reader-agnostic ingest loop
src/derive/          store glue around @turbo/kodo-core (Step 3)
src/daemon/          background watcher (Step 4)
src/sync/            upload to the API (Step 5)

Privacy

Readers never open the source files a transcript refers to. file.edited carries a repo-relative path and line counts only. Prompt text stays in the local prompt_text table and never leaves the machine unless you run kodo config set sync.prompts titles. Fixtures under __fixtures__/ are produced by scripts/kodo/redact-fixture.mjs and contain no text.