Docs

Keptrace records what your AI coding tools did and decided, then lets you search that record by date, repo and ref. The CLI is the only thing to install. Everything below documents what ships today.

Install

Log in once, then install the Claude Code hooks. Both commands run through npx, so there is nothing to add to your project.

shell
npx keptrace login
npx keptrace hooks install claude-code

Run npx keptrace status to confirm the account, workspace and hooks.

Commands

login
keptrace login [--api-url <url>]

Logs in with a device code and writes the token to the local config file. The API URL defaults to the hosted service.

  • --api-url <url>Point the CLI at a different API. Also read from KEPTRACE_API_URL.
status
keptrace status

Prints the config path, API URL, account and workspace, embedding runtime state, and whether the Claude Code hooks are installed.

hooks install
keptrace hooks install claude-code

Adds SessionStart, Stop and SessionEnd hooks to ~/.claude/settings.json. Idempotent: existing Keptrace entries are replaced, every other hook and setting survives. Remove them with hooks uninstall claude-code.

search
keptrace search <query> [--repo r] [--as-of iso] [--include-superseded] [--limit n] [--types turn,decision,session,digest] [--json]

Searches turns, decisions, sessions and digests in your workspace.

  • --repo <name>Restrict results to one repo.
  • --as-of <iso>Answer as of a date. Decisions carry validity windows, so you get the choice that held then.
  • --include-supersededAlso return decisions that were later replaced.
  • --limit <n>Maximum number of results, a positive integer.
  • --types <list>Comma-separated record types: turn, decision, session, digest.
  • --jsonMachine-readable output.
rollup
keptrace rollup [--dry-run]

Summarises ended sessions and writes weekly digests now, in the foreground. Use --dry-run to see what would be written.

How recording works

The hooks run at session start, at every stop, and at session end. They post turns to the API as they happen, tagged with the session, the repo and the refs the turn touched: files, symbols, commits and tickets.

Embeddings and summaries are computed locally on your machine. The embedding runtime installs on first use; until it is ready, search is text-only.

Each account has one workspace. All repos you record land in it, which is what lets a symbol touched in two repos link the turns in both.

Terminal output

Search results print one record per block: score, type, repo, date and how the match was found. Notices are prefixed with kept, warn or error.

$ npx keptrace search "workspace switch" --as-of 2026-08-21
keptrace · 3 results · as of 2026-08-21 00:00 UTC · via vector,ref
1. 0.91 decision keptrace · 2026-08-12 · via ref
   Postgres stays the system of record; ArcadeDB mirrors the graph
   → apps/api/app/Search/GraphRetriever.php
kept 14 turns from claude-code · session s_9f2c · keptrace
warn embedding runtime installing, search is text-only for ~1 min
error not logged in. Run: npx keptrace login

Privacy

Records are encrypted per tenant, capture can be switched off per repo, and delete means delete. Read the full policy at /privacy.