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

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

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.

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 tenants from one machine — say, a company tenant for work repos and a personal one for OSS. Each profile stores its own server_url, visibility default, daemon settings, and ignore list.

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:

--server-url CLI flag
KCAP_URL environment variable
KCAP_PROFILE environment variable
.kcap.json in the repo root (or current directory if not in a repo)
Git remote pattern matching from --remote flags
Directory binding from kcap use
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

Env vars take precedence over the profile’s config.