Configuration & profiles

The CLI stores configuration in ~/.config/kcap/config.json. You don’t usually edit it by hand — kcap config set and the profile commands cover everything. This page documents what’s in there and how the resolution order works.

Config keys

kcap config show
kcap config set <key> <value>

Key	Default	Description
server_url	(none)	Your Capacitor server URL, e.g. https://acme.kcap.ai. Set by kcap setup.
default_visibility	org_public	private, org_public, or public. Applied to every new session you create.
excluded_repos	(empty)	Comma-separated owner/repo list. Sessions in these repos are silently skipped.
daemon.claude_path	"claude"	Path to the Claude CLI binary, used by the daemon.
daemon.codex_path	"codex"	Path to the Codex CLI binary, used by the daemon.
disable_session_guidelines	false	If true, the CLI suppresses SessionStart guideline injection for your sessions.
use_provider_api_key	false	If true, the CLI keeps ANTHROPIC_API_KEY / OPENAI_API_KEY in the environment when it spawns Claude or Codex for headless calls (title generation, summaries, judges). See Provider API keys.
daemon.name	OS username	The daemon instance name, used by hosted agents. Overridable per launch with --name (or KCAP_DAEMON_NAME).
daemon.max_agents	5	Maximum concurrent hosted agents the daemon will run. Overridable with --max-agents or KCAP_MAX_AGENTS.
update_check	true	If false, the CLI skips its lazy background check for a newer release.
import_org	(none)	The repo owner remembered by kcap import --org. Written automatically the first time you pick one — you don’t usually set it by hand. See Import your history.

Visibility values:

Value	Who sees the session
private	Only the owner.
org_public	Anyone in the org that owns the repo (when the repo is recognised as an org repo). Personal repos fall back to private.
public	Anyone signed in to the Capacitor server.

See Visibility & sharing for how the per-session share popover layers on top of these.

Path exclusions

Separate from excluded_repos. kcap ignore matches the working directory (and any session whose cwd lives under it), regardless of git remote:

kcap ignore .                     # current directory
kcap ignore ~/code/secret
kcap ignore --list
kcap ignore --remove ~/code/secret

Symlinks are resolved on both the stored entry and the session’s reported cwd, so a worktree symlinked into another location matches its real target.

Entries are stored on the active profile, so switching profiles with kcap use switches the ignore list with you.

Provider API keys

Title generation, “what’s done” summaries, and the evaluation judge all shell out to claude -p or codex exec in the background. A globally-set ANTHROPIC_API_KEY or OPENAI_API_KEY would override your subscription auth (claude.ai / ChatGPT account) on those headless calls and surface as API errors, so by default the CLI scrubs both env vars before spawning the subprocess.

If you authenticate via API key on purpose (PAYG, no subscription), opt back in:

kcap config set use_provider_api_key true     # persist on the active profile
KCAP_USE_PROVIDER_API_KEY=1 kcap recap …      # one-shot override

kcap setup also prompts for this when either key is set in the current environment and the matching agent isn’t being skipped. In --no-prompt mode, pass --use-provider-api-key true (or false); the flag accepts true/1/yes/on and false/0/no/off, and any other value exits with an error rather than silently flipping the setting. Omit the flag to preserve the previous profile value.

The env var (KCAP_USE_PROVIDER_API_KEY) wins over the profile setting when set to a recognised value.

Renamed repo directories (kcap remap)

Historic transcripts record the absolute working directory they ran in. If you’ve since renamed or moved that directory on disk (e.g. ~/dev/foo-cli → ~/dev/bar-cli), kcap import --org / --repo can’t resolve those sessions to a GitHub repo any more and silently drops them from the matched count.

At the top of every import run, kcap prints a one-shot report of cwds that no longer exist on disk — that’s your cue to add a remap.

Ephemeral worktree cwds — paths shaped <project>/.<anything>/worktrees/<slug>, e.g. ~/dev/my-repo/.claude/worktrees/<slug> or ~/dev/my-repo/.capacitor/worktrees/<slug> — are auto-attributed to <project> when the project still exists on disk, so they never need a remap entry. The import surfaces a one-liner above the missing-cwds report telling you how many were recovered this way:

Attributed N sessions to a parent project via worktree path.

The pattern is intentionally generic: any single dot-prefixed segment followed by worktrees/<slug> is treated as an ephemeral worktree, so future tools that pick their own .something/worktrees/ layout work without code changes.

Manage rewrites with the kcap remap command:

kcap remap ~/dev/eventstore/foo-cli ~/dev/eventstore/bar-cli   # add or replace a mapping
kcap remap --list                                              # show all mappings
kcap remap --remove ~/dev/eventstore/foo-cli                   # drop one

Entries are stored at the top of ~/.config/kcap/config.json under a cwd_remap array — you can edit the file directly for bulk changes:

{
  "version": 2,
  "active_profile": "default",
  "profiles": { "default": { /* ... */ } },
  "cwd_remap": [
    { "from": "~/dev/eventstore/foo-cli", "to": "~/dev/eventstore/bar-cli" },
    { "from": "~/dev/eventstore/foo",     "to": "~/dev/eventstore/bar"     }
  ]
}

Semantics:

• from / to are path-prefix rewrites with ~ expanding to the current user’s home directory (~\ is also accepted on Windows).
• The match requires a path boundary — from equals the cwd exactly, or from is followed by / (or \ on Windows). So from: "~/dev/foo" will not spuriously rewrite ~/dev/foo-cli.
• Comparisons follow the host filesystem’s case policy: case-insensitive on Windows, case-sensitive elsewhere.
• When multiple rules could apply to the same cwd, the longest from wins.
• Rules are applied once (no chaining), so the result of one rule isn’t fed into another.
• Remaps are global, not per-profile — the same rename affects all profiles’ imports.

After adding a remap, re-run kcap import --org (or whichever scope you use). The missing-cwd report at the top of the import will show what’s still unresolved. Ephemeral worktree paths under <project>/.<anything>/worktrees/<slug> only appear here when <project> itself is also missing — when the project still exists on disk, those sessions are auto-attributed to it and don’t surface in the report.

Profiles

Profiles let you target multiple Capacitor servers from one machine — say, a company server for work repos and a personal one for OSS. Each profile stores its own server_url, visibility default, daemon settings, and ignore list.

When you sign in, discovery creates one profile per organization you belong to, named after the tenant slug — so switching between orgs is just a kcap use. See Setup CLI for how sign-in and tenant discovery work.

kcap profile add work --server-url https://acme.kcap.ai
kcap profile add oss --server-url https://cap.oss.dev --remote "github.com/myorg/*"
kcap profile list
kcap profile show work
kcap profile remove work

The --remote flag binds a profile to a git remote pattern. When you cd into a repo whose origin matches, that profile activates automatically.

Switching

kcap use work                  # bind 'work' to the current repo or directory
kcap use work --global         # set as the global default
kcap use work --save           # write .kcap.json (commit it for team-wide binding)

Without --global, use binds the profile to the current git repo root (or the current directory if not in a repo). With --save, it writes a .kcap.json you can commit so the whole team uses the same profile.

Resolution order

When the CLI needs to decide which profile to use, it consults these sources in order:

1. --server-url CLI flag
2. KCAP_URL environment variable
3. KCAP_PROFILE environment variable
4. .kcap.json in the repo root (or current directory if not in a repo)
5. Git remote pattern matching from --remote flags
6. Directory binding from kcap use
7. Global active profile (or default)

The first source that yields a profile wins.

Environment overrides

A few keys can be overridden by environment variables — useful for one-shot daemon launches or CI:

KCAP_URL=https://acme.kcap.ai kcap recap <id>
KCAP_PROFILE=work kcap status
KCAP_CLAUDE_PATH=/opt/claude/bin/claude kcap daemon
KCAP_CODEX_PATH=/opt/codex/bin/codex   kcap daemon
KCAP_USE_PROVIDER_API_KEY=1 kcap recap <id>    # keep provider API keys in headless spawns

Env vars take precedence over the profile’s config.