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.

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

Capacitor supports nine coding agents. Every one is both captured (sessions stream live) and importable (kcap import --<agent> backfills past runs), and every one can 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	✓

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 Capacitor 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 the current repository if it has a resolvable origin remote.

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.

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 Capacitor workspace, the wizard offers three ways to continue:

  Single sign-on found no Capacitor 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 Capacitor (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, 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 — 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://capacitor.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 the current repository’s history by default when the repository and authentication are available. 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.

Codex setup also configures sandbox network access to your Capacitor 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>.

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.

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.

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

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