Setup CLI

The CLI is the bridge between your coding agent and your kcap server. It installs hooks that fire automatically when Claude Code, Codex, Gemini CLI, Pi, OpenCode, Antigravity, Copilot CLI, Cursor, Kiro, Muse Code, Grok Build, or Mistral Vibe run, and it provides the commands you’ll use to recap, review, and evaluate sessions. This page walks through a fresh install.

Setup installs more than hooks: MCP servers, skills, and session-start context injections. The installed harness maps every piece with its file path — worth a read before (or right after) you run the wizard if you like to know exactly what lands on your machine.

Supported agents at a glance

kcap supports twelve coding agents. Every one is both captured (sessions stream live) and importable (kcap import --<agent> backfills past runs). The ten marked below can also be launched from the dashboard as a hosted agent — with the interaction mode depending on the vendor and daemon platform (see Hosted agents).

Agent	Detected by	Hooks flag	Hosted
Claude Code	claude on PATH	(default)	✓
Codex	codex on PATH	--codex	✓
Gemini CLI	Gemini settings/history under ~/.gemini/, or gemini on PATH	--gemini	✓
Pi	~/.pi/agent/ or pi on PATH	--pi	✓
GitHub Copilot CLI	~/.copilot/ or copilot on PATH	--copilot	✓
Cursor	~/.cursor/	--cursor	✓
Kiro	~/.kiro/, kiro, or kiro-cli on PATH	--kiro	✓
OpenCode	~/.config/opencode/, ~/.local/share/opencode/, or opencode on PATH	--opencode	✓
Antigravity	~/.gemini/antigravity/, ~/.gemini/antigravity-cli/, or antigravity / agy on PATH	--antigravity	✓
Muse Code	~/.config/muse/, ~/.local/share/muse/ (honouring XDG_CONFIG_HOME / XDG_DATA_HOME), or muse on PATH	--muse	✓
Grok Build	~/.grok/ or grok on PATH	--grok
Mistral Vibe	~/.vibe/ or vibe on PATH	--mistral-vibe

1. Install from npm

npm install -g @kurrent/kcap

npm picks the right native binary for your platform automatically:

Platform	Architectures
macOS	ARM64 (Apple Silicon)
Linux	x64, ARM64
Linux (Alpine / musl)	x64, ARM64
Windows	x64

The binary is NativeAOT-compiled — fast startup, no .NET runtime needed.

Install scripts

The native binary comes from a platform-specific optional dependency. Keep npm optional dependencies enabled. If npm reports that the platform package is missing, reinstall with:

npm install -g @kurrent/kcap --include=optional --prefer-online

The postinstall script refreshes integrations you previously installed. If your package manager blocks scripts, the CLI still works; run kcap setup for a fresh install or kcap update for an upgrade and integration refresh.

2. Run the setup wizard

kcap setup

You don’t need to know your server URL ahead of time. The wizard talks to Kurrent’s auth service, signs you in through single sign-on, and discovers every kcap server your identity has access to.

Setup guides you through:

1. Sign-in and workspace selection. Sign in through Kurrent’s hosted sign-in. Setup discovers your workspaces and asks you to choose when needed. A workspace using GitHub App authentication can be selected by URL with --github.
2. Browser setup, when offered by the server. The CLI opens a setup link and reports which agents it found on this machine. Choose Record and Tools independently for each agent, your session visibility, and the history to import. Your choices are applied locally; setup does not ask the same questions again. Not now installs no agent integrations. Keep the terminal running until it finishes. The printed link also works from another machine’s browser.
3. Terminal setup for any unanswered steps. Choose a visibility default (private, project, org_public, or public), then accept or decline installation for the detected agents. The terminal asks once for the integrations as a group. project visibility requires a Team or Enterprise plan.
4. Daemon and history. Setup saves a daemon name, defaulting to your OS username. If you asked for the agent daemon in browser setup, it installs or starts its OS service. Otherwise, you can enable it later for hosted agents. When history was not already chosen in the browser, setup offers to import this machine’s history.

Tokens are stored per profile under ~/.config/kcap/tokens/ (or $KCAP_CONFIG_DIR/tokens/). Agent integrations install user-wide unless you explicitly use a project-scope plugin install. When setup installs any agent’s hooks, it also adds a kcap hook to your global git config so each commit is filed under the agent session that made it (git 2.54+). The installed harness explains the hook and how to turn it off.

The next agent session you start opens with a short notice that setup completed and the hooks are loaded, and offers the guided tour. If an agent ran setup for you, that agent’s session is not recorded: agents load hooks, skills, and MCP servers only when a session starts.

Import this machine’s history

Setup scans every detected agent’s history on this machine, reports how many repositories and sessions it found and how many sessions matched no repository, then asks once whether to import them. The import covers the whole machine — the equivalent of kcap import --all — under your default visibility, subject to your capture scope.

The most recent sessions go first. About five import while you watch; the rest continue in a background process that logs to import-<run>.log in the kcap configuration directory (~/.config/kcap by default, or $KCAP_CONFIG_DIR), so you can close the terminal. Setup then offers to open one of your detected coding agents with the prompt Follow my kcap import, which runs the eval-watch skill: it follows this import and summarizes the first evaluations on those sessions. If you decline, setup prints the prompt to paste later.

Setup does not ask when you chose history in browser setup; it reports what ran. --skip-import skips the step.

First time? Sign up from the wizard

You don’t need an existing account — or workspace — before running kcap setup:

• No account yet — the hosted sign-in page that opens in your browser has a Sign up link at the bottom of the form. Create your account there, then return to the terminal.

• No workspace yet — after sign-in, if single sign-on turns up no kcap workspace, the wizard offers three ways to continue:

  Single sign-on found no kcap workspace for your account.
  A workspace that signs in with the GitHub App won't appear here.
  
  How would you like to continue?
  > Create a new workspace
    I already have a workspace
    Cancel

  Create a new workspace asks for your organization name and a workspace URL slug — lowercase letters, digits, and hyphens, up to 40 characters; the wizard checks availability as you type. Provisioning https://<slug>.kcap.ai takes a few minutes; the wizard waits for it to come online, then continues with the normal steps above. Workspaces created this way start on the Free plan.

  I already have a workspace is the option to take if you know you belong to one. Single sign-on only lists workspaces that use org SSO, so a workspace whose members sign in with the GitHub App can’t appear above even though you’re a member of it. Enter its slug or URL and setup points at that server; re-running with kcap setup --github gets you there too.

3. Verify

kcap whoami     # confirms you're logged in
kcap status     # checks the server is reachable

If both succeed, you’re connected.

Codex: trust the hooks

Codex requires you to trust newly added hooks before they fire. After the wizard installs Codex hooks, the next codex launch prompts to trust them — accept once to trust them all. Until you do, the hooks are installed but inert and no sessions will be captured.

If you’d rather trust each entry individually, run /hooks inside Codex and trust the kcap entries one by one.

If you only use the Codex desktop app, you’ll never see the CLI trust prompt — the app doesn’t show one. The wizard also detects Codex by the codex command on your PATH, so it may not have installed the hooks at all: run kcap plugin install --codex to install them, then open Settings → Hooks in the app and trust the kcap hooks. Until you do, sessions from the desktop app are not captured.

Claude Code loads its installed plugin in a fresh session. Cursor, Gemini CLI, Pi, OpenCode, Antigravity, Kiro, Muse Code, Grok Build, and Mistral Vibe have no trust prompt either; their hooks take effect the next time you start the agent (for OpenCode, restart any running opencode so it reloads the kcap plugin; for Antigravity, restart the IDE so it reloads the kcap plugin; for Muse Code, Grok Build, and Mistral Vibe, restart any running muse, grok, or vibe session). Installing Kiro support also clones your default kiro-cli agent and sets kcap as the default — kcap plugin remove --kiro restores the previous one.

Kiro Crew

Kiro Crew runs your installed kiro-cli under agent profiles it regenerates at every start, so the cloned default agent does not reach it. When Crew is present (~/.kiro/crew, or KIROCREW_HOME), kcap setup and kcap plugin install --kiro also write an executable ~/.kiro/hooks/kcap-spawn.sh and copy kcap’s skills into ~/.kiro/crew/skills. Restart Kiro Crew once afterwards so its agents pick up the hook.

Crew chats are then recorded, and each sub-agent a chat spawns is nested under it in the session view. Crew’s prompt wrapper is dropped, so a session shows the request you typed rather than Crew’s system text; sessions recorded before v1.2 keep their wrapped prompts.

• kcap setup --skip-kiro-hooks skips the Crew hook; --skip-kiro-skills skips the skills, on setup or kcap plugin install --kiro.
• kcap plugin remove --kiro removes both. A kcap-spawn.sh that kcap did not write is never overwritten or removed, and upgrades do not restore a hook or skills you deleted.
• Not available on Windows, where Crew cannot run shell hooks.

Targeting a specific server

The auto-discovery path is the right default for almost everyone. The two cases where you’d pass --server-url explicitly:

• Non-interactive setup — use --server-url for an existing workspace, or --org and --slug to create a first workspace. If the environment has nobody to sign in either (CI, agent sandboxes), pair it with a machine credential.
• Multiple servers per org, or off-discovery servers — when discovery wouldn’t pick the right one and you want to point at a known URL.

If you already know which workspace you want, kcap setup <tenant> is the short form of the same thing. A bare slug expands to https://<slug>.kcap.ai; anything that looks like a host or URL is used as-is:

kcap setup acme                            # same as --server-url https://acme.kcap.ai
kcap setup https://kcap.example.com   # a known server URL

The full non-interactive form:

kcap setup \
  --server-url https://acme.kcap.ai \
  --default-visibility org_public \
  --no-prompt \
  --skip-import

--no-prompt installs integrations for detected agents and imports every session on this machine by default when authentication is available — synchronously, without the background process or the agent hand-off. The example uses --skip-import so history is a separate choice. The flag also suppresses the import offer during interactive setup.

To create your first workspace with preselected names, use kcap setup --org "Acme" --slug acme --no-prompt --skip-import. The organization and slug flags go together and cannot be combined with a server URL or --github; sign-in is still required.

For SSH or a machine without a browser, add --device to sign in with a code on another device.

Opt out of a detected agent with its skip flag. For example:

kcap setup --server-url https://acme.kcap.ai --no-prompt --skip-import --skip-codex-hooks

Use kcap setup --help for the per-agent hook, MCP, skill, and instruction flags. Kiro’s hook flag skips its default-agent change; its tools have separate skip flags.

Muse Code has --skip-muse-hooks and --skip-muse-mcp; Grok Build has --skip-grok-hooks.

Codex setup also configures sandbox network access to your kcap servers in ~/.codex/config.toml, so CLI-backed skills can reach them. Pass --skip-codex-network-access to leave that network configuration alone.

If you authenticate Claude or Codex via API key (PAYG, no subscription) and want the CLI to pass that key through to its headless calls, add --use-provider-api-key true. By default the CLI scrubs ANTHROPIC_API_KEY / OPENAI_API_KEY to protect subscription-auth users — see Provider API keys for the full story.

Re-running discovery later

If you join a new org or want to add a second server to your profiles after the initial setup:

kcap login --discover

This runs just the sign-in-plus-server-picker leg of the wizard. New servers are added to your profile list; you can switch between them with kcap use <name>.

To list the workspaces your account can reach without configuring anything, run kcap setup --discover (add --json for a machine-readable report). It saves no profile or token, so the next command signs in again.

Installing hooks after the fact

If you install a new agent later, or want hooks scoped to a single repo instead of user-wide:

kcap plugin install                                            # Claude, user scope (default)
kcap plugin install --codex                                    # Codex hooks + agent skills, user scope
kcap plugin install [--gemini|--pi|--opencode|--antigravity|--cursor|--kiro|--copilot|--muse|--grok|--mistral-vibe]  # another agent's hooks, user scope
kcap plugin install --skills                                   # Agent skills only (~/.agents/skills/), no Codex hooks
kcap plugin install --project                                  # Claude, current repo only
kcap plugin install --codex --project                          # Codex hooks in <repo>/.codex/hooks.json, skills user-wide

Use --skills if you want Cursor (or another agent that reads ~/.agents/skills/) to have the kcap skills without installing Codex hooks.

Project-scope installs write to <repo>/.claude/settings.local.json (Claude) or <repo>/.codex/hooks.json (Codex). The command must run from inside a git working tree.

Upgrading kcap?

Use kcap update --check to check without changing anything. On the stable channel, updates are capped to the connected server’s version so your CLI stays compatible with your workspace.

The simplest upgrade is kcap update — it runs the npm upgrade and refreshes your user-scope skills, Codex/Gemini/Pi/OpenCode/Antigravity/Cursor/Kiro/Copilot hooks, and Claude plugin registration in one step (and works even when npm skips install scripts). npm install -g @kurrent/kcap refreshes them too, via the postinstall hook. Either way you usually don’t need to re-run kcap plugin install. Project-scope installs (--project) are not auto-refreshed — re-run the command manually for those. An upgrade does not add the git hook if it is missing; run kcap setup or kcap plugin install once to add it. Re-running kcap setup also updates the Codex MCP entries an earlier version wrote.

Custom agent config directories

If you keep an agent’s config somewhere other than its default, set that agent’s environment variable and kcap follows it — for detection, hook/plugin install, and import alike:

Agent	Env var	Points at
Claude Code	CLAUDE_CONFIG_DIR	Replaces ~/.claude.
Codex	CODEX_HOME	Replaces ~/.codex.
Gemini CLI	GEMINI_CLI_HOME	The parent of .gemini — kcap uses $GEMINI_CLI_HOME/.gemini.
OpenCode	OPENCODE_CONFIG_DIR	Overrides the config dir (session data still follows XDG_DATA_HOME → ~/.local/share/opencode).
Pi	PI_CODING_AGENT_DIR	The agent directory (default ~/.pi/agent).
GitHub Copilot CLI	COPILOT_HOME	Replaces ~/.copilot.
Kiro	KIRO_HOME	Replaces ~/.kiro.
Muse Code	XDG_CONFIG_HOME, XDG_DATA_HOME	Replace ~/.config (settings) and ~/.local/share (sessions). Muse runs hooks without these variables, so kcap plugin install --muse saves them for its hooks — re-run it after changing either.
Grok Build	GROK_HOME	Replaces ~/.grok.
Mistral Vibe	VIBE_HOME	Replaces ~/.vibe.

Set the variable before kcap setup — and in the environment your agent actually runs in — so detection and capture agree on the same location.

What’s next

Restart any already-running agents so they load their new integrations. Capture your first session in Your first session.