Setup CLI

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

Supported agents at a glance

Capacitor supports nine coding agents. Every one is both captured (sessions stream live) and importable (kcap import --<agent> backfills past runs). Launching from the dashboard as a hosted agent is Claude Code and Codex only today; the rest are capture-only.

Agent	Detected by	Hooks flag	Hosted
Claude Code	`claude` on `PATH`	(default)	✓
Codex	`codex` on `PATH`	`--codex`	✓
Gemini CLI	`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`	—
OpenCode	`~/.config/opencode/`, `~/.local/share/opencode/`, or `opencode` on `PATH`	`--opencode`	—
Antigravity	`~/.gemini/antigravity/` or `antigravity` on `PATH`	`--antigravity`	—

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.

The native binary ships as a platform-specific npm package (an optional dependency), so kcap runs as soon as the package installs — nothing is downloaded by a script. The package’s postinstall hook does one thing: refresh your agent plugins (Claude plugin, Codex/Gemini/Pi/OpenCode/Antigravity/Cursor/Kiro/Copilot hooks, agent skills) on install and upgrade.

npm is moving dependency install scripts to opt-in (blocked by default) — rolling out across npm 11.16+ and becoming the default in npm v12. When the postinstall is blocked, the package still installs and kcap still runs; only the agent-plugin refresh is skipped.

The simplest fix is to upgrade with kcap update instead of npm install -g. It performs the npm upgrade and refreshes your plugins in-process, so it works regardless of npm’s install-script policy — no opt-in required.

If you prefer to upgrade with npm directly and want the postinstall to run, opt the package in for global installs:

# persistent — add to ~/.npmrc
allow-scripts[]=@kurrent/kcap

# or one-off, per install
npm install -g @kurrent/kcap --allow-scripts=@kurrent/kcap

npm approve-scripts does not work for global installs (npm/cli#9463), so allow-scripts is the global opt-in. Either way, you can always refresh plugins by hand without allowing scripts:

kcap plugin install [--codex|--gemini|--pi|--opencode|--antigravity|--cursor|--kiro|--copilot|--skills] --if-installed

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 Capacitor server your identity has access to.

The flow you’ll actually see:

Sign in — your browser opens to Kurrent’s hosted sign-in (single sign-on). Approve the sign-in and come back to the terminal. Tokens land in ~/.config/kcap/tokens.json.
Pick your server — the wizard prints the list of Capacitor servers you can sign into (one per organization with a Capacitor server). On a single-server team this is one-click; if you belong to multiple organizations you get a picker.
Default visibility — private, org_public (default), or public. Changeable later via kcap config set default_visibility …. See Visibility & sharing for what each value means.
Coding-agent hooks — the wizard detects Claude Code (claude), Codex (codex), and Gemini CLI (gemini) on your PATH, Cursor and Kiro by their user dirs (~/.cursor/, ~/.kiro/), Pi by ~/.pi/agent/ or pi on PATH, OpenCode by ~/.config/opencode/ (or ~/.local/share/opencode/) or opencode on PATH, Antigravity by ~/.gemini/antigravity/ or antigravity on PATH, and GitHub Copilot CLI by ~/.copilot/ or copilot on PATH, and offers to install hooks for each. Pick yes for whichever you use.
Daemon — names the daemon process used for hosted agents. Defaults to your OS username; accept the default unless you’ll run multiple daemons on the same machine.

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 no Capacitor workspace is linked to your account, the wizard offers to create one:
```
No Capacitor tenant is linked to your account.
Create one now?
```
Name your organization and pick 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.

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.

Claude Code has no equivalent trust step — its hooks fire immediately. Cursor, Gemini CLI, Pi, OpenCode, Antigravity, and Kiro 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). Installing Kiro support also clones your default kiro-cli agent and sets kcap as the default — kcap plugin remove --kiro restores the previous one.

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 — --no-prompt requires --server-url because there’s no terminal to show the picker on.
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.

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

In --no-prompt mode, hooks install for every detected agent by default. Opt out per agent:

kcap setup --server-url … --no-prompt --skip-codex-hooks --skip-gemini-hooks --skip-pi-hooks --skip-opencode-hooks --skip-antigravity-hooks --skip-cursor-hooks --skip-kiro-hooks --skip-copilot-hooks   # Claude only
kcap setup --server-url … --no-prompt --skip-claude-hooks --skip-gemini-hooks --skip-pi-hooks --skip-opencode-hooks --skip-antigravity-hooks --skip-cursor-hooks --skip-kiro-hooks --skip-copilot-hooks  # Codex only

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>.

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]  # 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.

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`.

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

You’re ready. Capture your first session in Your first session.