Configuration & profiles

The CLI stores configuration in ~/.config/kcap/config.json, or under KCAP_CONFIG_DIR when set. Use the configuration, profile, allow, and ignore commands to change it. This page documents what’s in there and how the resolution order works.

Config keys

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

In v1.1.1, config set and config unset change the global active profile, even when the current repository or KCAP_PROFILE selects a different profile for server requests. Run kcap use <name> --global before editing that profile. telemetry is machine-wide.

Setting server_url normally probes the server first. Add --no-probe to save a URL without checking connectivity: kcap config set server_url <url> --no-probe.

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, project, org_public, or public. Applied to every new session you create.
allowed_repos	(empty)	Comma-separated owner/repo allow list. Empty allows all repos; a nonempty list captures only named repos.
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.
disable_memory_index	false	If true, the CLI skips injecting the shared memory index at SessionStart. Independent of disable_session_guidelines.
disable_coordination_notices	false	Suppress session-start notices about overlapping work.
disable_workitems_nudge	false	Suppress the reminder to attach the session to a work item.
disable_plans_nudge	false	Suppress the reminder to declare plans and tasks.
disable_harness_nudge	false	Suppress setup reminders for newly detected agents.
flows.reviewer_vendor	(unset)	Preferred review-flow vendor when the flow definition names none.
skills.auto_sync	false	Refresh server-managed skill documents in the background at Claude session start.
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; 0 means unlimited. Overridable with --max-agents or KCAP_MAX_AGENTS.
update_check	true	If false, suppress CLI update hints, server update banners/notifications, and the in-agent update nudge.
telemetry	on	Anonymous CLI usage reporting, set with on or off. Machine-wide, rather than per profile.

Visibility values:

Value	Who sees the session
private	Only the owner.
project	Members of the project(s) the repo belongs to. Team / Enterprise plans only.
org_public	Uses the server’s configured organization/repository rules and applicable project membership. Personal or unrecognized repositories can remain private.
public	Anyone signed in to the Capacitor server.

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

Capture scope

By default, all paths and repositories are eligible for recording. An allow list narrows that scope; exclusions remove work inside it.

kcap allow ~/dev/work                 # capture only this directory tree
kcap allow --list
kcap allow --remove ~/dev/work

kcap ignore ~/dev/work/private        # exclude a subtree
kcap ignore --list
kcap ignore --remove ~/dev/work/private

kcap config set allowed_repos "acme/api,acme/web"
kcap config set excluded_repos "acme/private"

The rules apply to live capture and history imports:

• If a path allow list is set, the session’s working directory must be at or below an allowed path.
• If a repository allow list is set, the repository must match a listed owner/repo.
• When both are set, the session must pass both. An exclusion always wins.
• A session with an unknown working directory or repository cannot pass the corresponding allow list.

Paths resolve . and ~, directory boundaries, and symlinks. Entries are stored per profile. Removing the last allowed path, or setting allowed_repos to an empty string, removes that restriction and allows all paths or repositories again. Changing a capture list does not remove sessions already uploaded.

Unattended hosted launches, such as flow participants, also respect these lists. They are checked against the originating checkout, including when execution uses a separate snapshot. A checkout outside the scope is refused with out_of_capture_scope. An agent you explicitly launch is treated separately; choosing its directory is consent to that launch.

Other stored settings

allowed_paths and excluded_paths are maintained by kcap allow and kcap ignore. import_org remembers the repository owner selected by kcap import --org; update_channel is set by kcap update --beta or --stable. These are stored settings, not additional config set keys.

Use kcap config unset flows.reviewer_vendor or kcap config unset skills.auto_sync to remove either override. Other keys use config set with their desired value.

Provider API keys

Local headless operations, such as CLI evaluations, can spawn claude -p or codex exec. Server-generated session outcomes use the server’s configured summary provider. 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 eval <sessionId>  # 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 '~/dev/repo/worktrees/*' ~/dev/repo              # match one worktree directory segment
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.
• from can contain one * as a complete path segment. It matches exactly one directory name. Quote the pattern so your shell does not expand it. The destination is literal; it cannot contain a wildcard. Any remaining path suffix is preserved.
• The rule consuming the most of the original path wins. A literal rule wins a tie against a wildcard rule.
• 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, capture lists, and feature toggles.

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.

profile add also accepts --no-probe to skip the server connectivity check. profile show without a name displays the stored global active profile. See the command reference for every profile command and option.

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 start
KCAP_CODEX_PATH=/opt/codex/bin/codex   kcap daemon start
KCAP_CURSOR_PATH=/opt/cursor/bin/cursor-agent kcap daemon start   # locate cursor-agent for hosted Cursor over ACP
KCAP_USE_PROVIDER_API_KEY=1 kcap eval <id>     # keep provider API keys in headless spawns

Env vars take precedence over the profile’s config. daemon.claude_path and daemon.codex_path are also persistable profile keys (above); the Cursor binary is resolved from PATH and overridable only through KCAP_CURSOR_PATH (there is no daemon.cursor_path key) — see Hosted agents.

KCAP_TELEMETRY=0 disables anonymous CLI usage reporting for the process. DO_NOT_TRACK=1 also opts out; an explicit KCAP_TELEMETRY value takes precedence over it and the saved setting.

KCAP_CLIENT_ID / KCAP_CLIENT_SECRET are different in kind: when either is present, the CLI stops using the profile’s stored login and authenticates as a machine instead. They belong on CI runners, not in interactive shells.