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 <tenant>                          # a known workspace, by slug or URL
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

kcap machine create <name>                   # headless credential for CI / sandboxes (secret shown once)
kcap machine list                            # this org's machines
kcap machine revoke <service-id>             # stop a machine authenticating

Tokens are stored at ~/.config/kcap/tokens/<profile>.json, one file per profile (under $KCAP_CONFIG_DIR instead, if you set it), and refresh automatically; if the cached token can’t be refreshed, the next CLI call reprompts you to sign in. Where nobody can sign in at all — CI runners, agent sandboxes — a machine credential replaces login entirely.

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.

Projects

kcap projects              # list projects you can see (slug, name, repo count, member count, your role)
kcap project <slug>        # one project's detail: repos, members, and (owners/admins) pending requests

Both require the Team or Enterprise plan; the server returns a 403 on Free. More: Home & projects.

MCP servers (for agents)

kcap mcp sessions                           # stdio MCP server: search past sessions
kcap mcp review                             # stdio MCP server: PR review context
kcap mcp flows                              # stdio MCP server: run iterative review flows
kcap mcp workitems                          # stdio MCP server: declare/list a session's work items
kcap mcp memory                             # stdio MCP server: shared team memory (read + write)
kcap mcp analytics                          # stdio MCP server: governed read-only analytics SQL

kcap setup auto-registers kcap mcp sessions for every supported agent — Claude Code and Codex out of the box, Cursor, Gemini CLI, Kiro, OpenCode, Antigravity, and GitHub Copilot CLI through their own config files, and Pi through its extension bridge (Pi has no native MCP); see Session recall and The installed harness for the full per-agent map.

The server is repo-aware — cd into a project before launching the agent and search_sessions defaults to that repo. Five tools: search_sessions, get_session_summary, get_session_transcript, list_turns, 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. Auto-registered for every supported agent by kcap setup; because starting a flow launches a paid hosted reviewer, its tools are never auto-approved.

kcap mcp workitems exposes seven tools — declare_work_item and get_session_work_items for attaching the current session to a work item, plus declare_work_breakdown, retract_work_breakdown, declare_work_relation, retract_work_relation, and get_work_item_topology for declaring its structure. Auto-registered for every supported agent by kcap setup. See Work items.

kcap mcp memory is the team-memory server — durable, shared knowledge agents can search and write (search_memories, get_memory, save_memory, update_memory, rescope_memory, archive_memory). Auto-registered for every supported agent by kcap setup; because it can write, it prompts for approval rather than auto-approving. See Team memory.

kcap mcp review serves PR review context — the PR summary, changed files, and the implementation sessions behind them (get_pr_summary, list_pr_files, get_file_context, search_context, list_sessions, get_transcript). Read-only; auto-registered for every supported agent by kcap setup.

kcap mcp analytics exposes the governed Insights query API (get_analytics_schema, query_analytics) — read-only SQL over the analytics views. Auto-registered for every supported agent by kcap setup; requires the Team or Enterprise plan (the whole endpoint group is plan-gated, reads included).

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 product in two forms — the GUI IDE and the agy CLI — both sharing the ~/.gemini home. kcap import --antigravity backfills conversations from both roots (~/.gemini/antigravity/brain/ for the GUI and ~/.gemini/antigravity-cli/brain/ for the agy CLI), and kcap plugin install --antigravity captures new ones live — both are supported. A machine with only the agy CLI (no GUI) is still detected by kcap setup. 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 agent start claude             # run a daemon-hosted agent in your terminal (Unix only)
kcap agent start codex --worktree   # ...in a throwaway git worktree
kcap agent start claude --private   # ...purely local (not registered with the server)
kcap agent attach <agent-id>        # re-attach to a running agent (Ctrl-Q then d to detach)
kcap agent 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.

Service status