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                                   # sign in (browser)
kcap login --device                          # device flow (SSH / headless)
kcap login --discover                        # re-discover which servers you can reach
kcap logout                                  # delete stored tokens
kcap whoami                                  # show authenticated user
kcap status                                  # server health check

Tokens are stored at ~/.config/kcap/tokens.json and refresh automatically; if the cached token can’t be refreshed, the next CLI call reprompts you to sign in.

See Setup 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 recap --per-turn <sessionId>         # compact per-turn index
kcap recap --get-turn <N> <sessionId>     # full transcript for turn N

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 any agent session with Capacitor hooks 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.

Curation

kcap curate apply             # write promoted CLAUDE.md guidelines into this repo
kcap curate apply --dry-run   # preview the changes, write nothing
kcap curate apply --yes       # apply without the confirmation prompt

Run inside a git repo; the owner/name come from its remote. More: Curation write-back.

MCP servers (for agents)

kcap mcp sessions                           # stdio MCP server: search past sessions
kcap mcp flows                              # stdio MCP server: run iterative review flows
kcap mcp workitems                          # stdio MCP server: declare/list a session's work items

The Capacitor plugin (installed by kcap setup) auto-registers kcap mcp sessions for both Claude Code and Codex CLI, so it’s available out of the box on either harness. Other MCP-aware clients — Cursor, Gemini CLI, Kiro, OpenCode, Antigravity, GitHub Copilot CLI — can point at kcap mcp sessions directly; see Session recall.

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

kcap mcp flows is a separate server for review flows — the iterative findings → fix → re-review → sign-off loop, distinct from kcap review. Register it per agent (e.g. claude mcp add kcap-flows -- kcap mcp flows).

kcap mcp workitems exposes two tools — declare_work_item and get_session_work_items — for attaching the current session to a work item and listing its attachments. It’s auto-registered by the kcap Claude Code plugin and is Claude Code only. See Work items.

Importing past sessions

kcap import                                   # everything detected
kcap import --all                             # every session/repo
kcap import --claude                          # only Claude sessions
kcap import --codex                           # only Codex sessions
kcap import --gemini                          # only Gemini CLI sessions
kcap import --pi                              # only Pi sessions
kcap import --copilot                         # only Copilot CLI sessions
kcap import --cursor                          # only Cursor agent sessions
kcap import --kiro                            # only Kiro agent sessions
kcap import --opencode                        # only OpenCode sessions
kcap import --antigravity                     # only Antigravity sessions
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)

OpenCode imports from its local SQLite database (~/.local/share/opencode/opencode.db). The first OpenCode import fetches a small SQLite native library into ~/.cache/kcap (mirror it with KCAP_SQLITE_NATIVE_BASE_URL for airgapped installs). OpenCode is still captured live via the shipped plugin too (kcap plugin install --opencode).

Antigravity is Google’s agent IDE (it shares the ~/.gemini home). kcap import --antigravity backfills conversations from ~/.gemini/antigravity/brain/, and kcap plugin install --antigravity captures new ones live — both are supported. Imported Antigravity sessions carry their transcript but not per-generation cost.

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 --gemini                # Gemini CLI hooks (merged into ~/.gemini/settings.json)
kcap plugin install --pi                    # Pi extension (~/.pi/agent/extensions/kcap.ts)
kcap plugin install --opencode              # OpenCode plugin (~/.config/opencode/plugins/kcap.ts)
kcap plugin install --antigravity           # Antigravity plugin (~/.gemini/config/plugins/kcap/)
kcap plugin install --copilot               # Copilot CLI hooks (~/.copilot/hooks/kcap.json)
kcap plugin install --cursor                # Cursor hooks (~/.cursor/hooks.json)
kcap plugin install --kiro                  # Kiro agent (~/.kiro/agents/kcap.json)
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 --gemini                 # Remove Gemini CLI hooks from ~/.gemini/settings.json
kcap plugin remove --pi                     # Remove the Pi extension
kcap plugin remove --opencode               # Remove the OpenCode plugin
kcap plugin remove --antigravity            # Remove the Antigravity plugin
kcap plugin remove --cursor                 # Remove Cursor hooks
kcap plugin remove --kiro                   # Remove the Kiro agent (restores the previous default)
kcap plugin remove --copilot                # Delete kcap's Copilot hooks file
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 simplest way to upgrade is kcap update — it runs the npm upgrade and then refreshes your user-scope skills (~/.agents/skills/kcap-*), Codex hook commands (~/.codex/hooks.json), Gemini CLI / Pi / OpenCode / Kiro hooks, Cursor hooks (~/.cursor/hooks.json), Copilot hooks file (~/.copilot/hooks/kcap.json), and Claude plugin registration (~/.claude/settings.json) in one step. It works even when npm is configured to skip install scripts (see Install from npm).

If you upgrade with npm install -g @kurrent/kcap instead, the same refresh runs via the npm postinstall hook. Either way, 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.

You can also run the refresh commands by hand:

kcap plugin install [--codex|--gemini|--pi|--opencode|--antigravity|--cursor|--kiro|--copilot] --if-installed   # Refresh one agent's hooks if previously installed
kcap plugin install --skills --if-installed                                            # Refresh agent skills if previously installed
kcap plugin install --if-installed                                                     # Refresh the Claude plugin registration 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 daemon service install         # supervise as a launchd/systemd/Scheduled Task service (auto-restart on crash/SIGKILL)
kcap daemon service status
kcap daemon service stop            # stop the service but keep it installed
kcap daemon service start           # start it again after a stop
kcap daemon service uninstall       # stop and remove the service

kcap run-agent claude               # run a daemon-hosted agent in your terminal (Unix only)
kcap run-agent codex --worktree     # ...in a throwaway git worktree
kcap run-agent claude --private     # ...purely local (not registered with the server)
kcap attach <agent-id>              # re-attach to a running agent (Ctrl-Q then d to detach)
kcap ls                             # list the daemon's agents (id, status, repo)

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                         # upgrade the CLI and refresh agent plugins

For npm-global installs, kcap update upgrades to the latest published version and refreshes your agent plugins (skills, Codex/Gemini/Pi/OpenCode/Antigravity/Cursor/Kiro/Copilot hooks, Claude plugin) in one step — regardless of whether npm runs install scripts. It exits early if you’re already up to date, and prints the right command for non-npm installs (e.g. Homebrew). The CLI also checks for a newer release lazily in the background (24-hour cache) and prints a hint when one is available.

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, Gemini CLI, Cursor, and Kiro hook files (preserving any non-kcap entries), deletes the Pi live-ingest extension (~/.pi/agent/extensions/kcap.ts) the OpenCode plugin (~/.config/opencode/plugins/kcap.ts), and the Antigravity plugin (~/.gemini/config/plugins/kcap/), deletes kcap’s Copilot hooks file (~/.copilot/hooks/kcap.json), 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.