Commands

The kcap CLI command surface, grouped by what you’d reach for. For every command, kcap <command> --help gives the full flag list. This page is a navigable summary.

Setup and auth

kcap setup                                   # interactive wizard
kcap setup --server-url <url> --no-prompt    # scripted / CI
kcap login                                   # OAuth in browser
kcap login --device                          # device flow (SSH / headless)
kcap logout                                  # delete stored tokens
kcap whoami                                  # show authenticated user
kcap status                                  # server health check

Tokens are stored at ~/.config/kcap/tokens.json. Auth0 tokens auto-refresh; direct GitHub tokens expire after 24 hours and the next CLI call will reprompt.

See Install the CLI for the wizard walkthrough.

Session lookup

kcap recap <sessionId>                    # AI-generated summary
kcap recap --full <sessionId>             # complete transcript
kcap recap --chain <sessionId>            # across the continuation chain
kcap recap --chain --full <sessionId>

kcap errors <sessionId>                   # extract tool-call errors
kcap errors --chain <sessionId>

kcap validate-plan <sessionId>            # verify all plan items completed

The identifier can be a session GUID or a meta-session slug. Inside Claude or Codex with the plugin installed, the session ID is resolved from the environment automatically.

More: Session recap, Errors & plan validation.

Recording control

kcap hide                  # mark current session owner-only
kcap hide <sessionId>      # specific session

kcap disable               # stop recording + delete server data (irreversible)
kcap disable <sessionId>

kcap ignore .              # ignore current directory (no capture for sessions under it)
kcap ignore ~/code/x
kcap ignore --list
kcap ignore --remove ~/code/x

More: Visibility & sharing.

Evaluations and review

kcap eval <sessionId>                       # LLM-as-judge, 13 questions
kcap eval --model opus <sessionId>
kcap eval --chain <sessionId>
kcap eval --questions safety <sessionId>
kcap eval --skip efficiency <sessionId>
kcap eval --threshold 5000 <sessionId>
kcap eval --list-questions

kcap review <pr-url>                        # Claude with MCP context tools

More: Evaluations, PR review.

MCP servers (for agents)

kcap mcp sessions                           # stdio MCP server: search past sessions

The Capacitor plugin (installed by kcap setup) auto-registers this server for both Claude Code and Codex CLI, so it’s available out of the box on either harness.

The server is repo-aware — cd into a project before launching the agent and search_sessions defaults to that repo. Three tools: search_sessions, get_session_summary, get_session_transcript. See Session recall.

Importing past sessions

kcap import                                   # everything detected (Cursor = current workspace)
kcap import --all                             # every session/repo (Cursor still narrows to current workspace)
kcap import --claude                          # only Claude sessions
kcap import --codex                           # only Codex sessions
kcap import --cursor                          # only Cursor (current workspace)
kcap import --cursor --cursor-all-workspaces  # only Cursor, every workspace
kcap import --cursor --cursor-workspace ~/p   # only Cursor, one specific workspace
kcap import --org                             # narrow by scope: org repos
kcap import --repo owner/name                 # narrow by scope: one repo
kcap import --repo .                          # narrow by scope: current cwd's repo
kcap import --org --yes                       # skip confirmation
kcap import --org --private                   # mark as Only Visible to You
kcap import --org --since 2026-01-01          # on or after this date
kcap import --org --cwd /path/to/project      # filter by working directory
kcap import --org --session abc123            # single session (dashed or dashless GUID)

More: Import your history.

Hooks and plugin

kcap plugin install                         # Claude hooks, user scope
kcap plugin install --codex                 # Codex hooks + agent skills, user scope
kcap plugin install --skills                # Agent skills only (~/.agents/skills/), no Codex hooks
kcap plugin install --project               # Claude hooks, current repo
kcap plugin install --codex --project       # Codex hooks in <repo>/.codex/hooks.json, skills user-wide
kcap plugin remove --codex                  # Remove Codex hooks + agent skills
kcap plugin remove --skills                 # Remove agent skills

--skills installs the five kcap skills (kcap-recap, kcap-errors, kcap-hide, kcap-disable, kcap-validate-plan) to ~/.agents/skills/. Codex, Cursor, and any agent that honours the .agents/skills/ convention picks them up automatically. Use --codex instead to also install Codex hooks.

Project-scope installs must be run from inside a git working tree. Skills are always user-wide; --project only affects hooks.

Refresh on upgrade

The npm postinstall hook refreshes all user-scope kapacitor installations on every npm install -g @kurrent/kapacitor, so you always pick up the current CLI version’s skills (~/.agents/skills/kapacitor-*), Codex hook commands (~/.codex/hooks.json), and Claude plugin registration (~/.claude/settings.json). Each refresh is gated on a marker file written by your previous setup — fresh systems that never opted in are left untouched, and project-scope installs (--project) are not auto-refreshed.

These refresh commands are normally invoked by the postinstall hook, but you can run them by hand:

kapacitor plugin install --skills --if-installed    # Refresh skills only if previously installed
kapacitor plugin install --codex --if-installed     # Refresh Codex hooks only if previously installed
kapacitor plugin install --if-installed             # Refresh Claude plugin registration only if previously installed

Errors during a --if-installed refresh are swallowed so the upgrade never breaks npm install.

Daemon

kcap daemon start                   # foreground (default --name = OS username)
kcap daemon start -d                # background
kcap daemon start --name laptop -d
kcap daemon status
kcap daemon status --name laptop
kcap daemon stop --name laptop
kcap daemon stop --yes              # stop all, no prompt
kcap daemon doctor                  # diagnose lock-file state
kcap daemon doctor --clean          # also remove stale lock/pid files

kcap repos                          # list known repos
kcap repos add .
kcap repos remove ~/dev/old

More: Hosted agents.

Configuration and profiles

kcap config show
kcap config set <key> <value>

kcap profile add work --server-url https://acme.kcap.ai
kcap profile list
kcap profile show work
kcap profile remove work

kcap use work                       # bind 'work' to current repo
kcap use work --global              # set as global default
kcap use work --save                # write .kcap.json (team-share)

More: Configuration & profiles.

Other

kcap update                         # check npm for a newer release

The CLI checks for updates lazily (24-hour cache). To force a check, just run kcap update.

Uninstall

To remove kcap from this machine, run:

kcap uninstall                  # interactive, user-scope removal
kcap uninstall --yes            # non-interactive
kcap uninstall --project --yes  # also strip project-scope hooks in cwd's repo
kcap uninstall --keep-config    # remove integrations, keep ~/.config/kcap

uninstall covers every supported agent in one go: it stops running daemons and watcher processes, strips kcap entries from user-level Claude Code, Codex CLI, and Cursor hook files (preserving any non-kcap entries), removes agent skills under ~/.agents/skills/ (plus the legacy ~/.codex/skills/kcap-* folders), and deletes ~/.config/kcap/.

--project additionally cleans up <repo>/.claude/settings.local.json and <repo>/.codex/hooks.json in the current git working tree (errors if you’re not inside one). Cursor only has a user-scope hooks.json, so --project does not affect it. Project-scope hooks in other repos are not touched — re-run from each repo that has them.

Use --keep-config to preserve profiles, tokens, and ignore lists when you plan to reinstall. For finer-grained removal (only Codex hooks, only Cursor, only skills), use kcap plugin remove [--codex|--cursor|--skills] instead.