Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 29 additions & 23 deletions evals/quality/cases/kurrent-capacitor-cli.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -7,39 +7,45 @@
value: >-
Directs the user to run `kcap setup` (the interactive wizard) and describes
the steps it covers: entering the server URL (provided by their admin),
logging in with GitHub, choosing default visibility, and installing
coding-agent hooks. The default GitHub login is browser-based OAuth (localhost
callback + PKCE); Device Flow is only the fallback for headless/SSH
environments or when `--device` is passed, so an answer that says login opens
a browser by default is CORRECT and must not be penalized, and an answer that
claims Device Flow is the default is wrong. Mentions verifying with
`kcap whoami` and/or `kcap status`. Does NOT invent commands like `kcap init`,
`kcap start`, or a config file the user must hand-write.
logging in, choosing default visibility, and installing coding-agent hooks.
At login the user picks how to sign in — email / SSO (WorkOS) or GitHub — so
an answer that mentions either method (or both) is correct; do NOT require it
to say GitHub specifically. For the GitHub path, login is browser-based OAuth
(localhost callback + PKCE) by default and Device Flow is only the fallback for
headless/SSH or when `--device` is passed, so an answer that says GitHub login
opens a browser by default is CORRECT and one that claims Device Flow is the
default is wrong. Mentions verifying with `kcap whoami` and/or `kcap status`.
Does NOT invent commands like `kcap init`, `kcap start`, or a config file the
user must hand-write.
- type: llm-rubric
value: >-
Notes that recording only happens once a supported coding agent (Claude Code,
Codex CLI, or Cursor) is installed and its hooks are in place. Setup alone,
which just detects agents and writes hook registrations, captures nothing. The
hook firing when the agent runs is the only trigger, so there is no recording
without a supported agent. Accepts (does not penalize) answers that mention
only Claude Code and/or Codex, but treats naming Codex CLI as the sole second
agent (omitting Cursor) as incomplete rather than correct. Does not require the
phrase "on PATH": detection is PATH-based for Claude and Codex but
directory-based for Cursor, so an answer that hinges recording solely on an
agent being "on PATH" is imprecise.
Notes that recording only happens once a supported coding agent is installed
and its hooks are in place. The supported agents are Claude Code, Codex CLI,
Cursor, Copilot CLI, Gemini CLI, Kiro CLI, Pi, and OpenCode; since the user
asked about Claude Code, an answer focused on Claude Code is fine and need not
enumerate the rest. Setup alone, which just detects agents and writes hook
registrations, captures nothing. The hook firing when the agent runs is the
only trigger, so there is no recording without a supported agent. Does not
require the phrase "on PATH": detection is PATH-based for some agents but
directory-based for others (e.g. Cursor via `~/.cursor/`), so an answer that
hinges recording solely on an agent being "on PATH" is imprecise.

- description: "[setup] Non-interactive setup, Claude hooks only"
vars:
skill: kurrent-capacitor-cli
message: "How do I run kcap setup in CI with no prompts, installing only the Claude Code hooks and skipping Codex and Cursor?"
message: "How do I run kcap setup in CI with no prompts, installing only the Claude Code hooks and no other agents?"
assert:
- type: llm-rubric
value: >-
Shows `kcap setup --server-url <url> --no-prompt` and explains that
`--no-prompt` installs hooks for EVERY detected agent by default, so you must
opt out of the others with `--skip-codex-hooks` and `--skip-cursor-hooks` to
get Claude-only. Uses these exact opt-out flags (not invented ones like
`--only-claude` or `--agents=claude`).
`--no-prompt` installs hooks for EVERY detected agent by default, so to get
Claude-only you must opt out of every other agent with its `--skip-<agent>-hooks`
flag: `--skip-codex-hooks`, `--skip-cursor-hooks`, `--skip-copilot-hooks`,
`--skip-gemini-hooks`, `--skip-kiro-hooks`, `--skip-pi-hooks`, and
`--skip-opencode-hooks`. Uses these `--skip-*-hooks` opt-out flags (not invented
ones like `--only-claude` or `--agents=claude`). An answer that only skips Codex
and Cursor, leaving the newer agents (Copilot/Gemini/Kiro/Pi/OpenCode)
installable, is incomplete.

- description: "[import] Backfilling past sessions requires an explicit scope"
vars:
Expand Down
15 changes: 15 additions & 0 deletions evals/trigger/kurrent-capacitor-cli.json
Original file line number Diff line number Diff line change
Expand Up @@ -88,5 +88,20 @@
"query": "How do I give Claude transcript context from past Capacitor sessions when reviewing a PR?",
"should_trigger": true,
"note": "mcp-review — kcap review / kcap mcp PR context, references/mcp-review.md"
},
{
"query": "How do I get kcap to record my Gemini CLI sessions into Capacitor?",
"should_trigger": true,
"note": "install/setup + plugins — newly supported agent (Gemini); kcap now records 8 agents, not just Claude/Codex/Cursor"
},
{
"query": "How do I write a prompt for the Gemini CLI to summarize a file?",
"should_trigger": false,
"note": "DEFER — using the Gemini CLI itself, not recording it with kcap; guards the new agent-name collision introduced by listing Gemini as a supported vendor"
},
{
"query": "How do I enable GitHub Copilot inline suggestions in VS Code?",
"should_trigger": false,
"note": "DEFER — Copilot IDE feature, unrelated to kcap session recording; guards the Copilot name collision now that Copilot CLI is a supported vendor"
}
]
13 changes: 9 additions & 4 deletions plugins/kurrent/skills/kurrent-capacitor-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@ name: kurrent-capacitor-cli
description: >-
Use when installing, configuring, or operating the kcap CLI, aka the
Kurrent Capacitor CLI / Capacitor CLI (npm @kurrent/kcap), which records
Claude Code, Codex, and Cursor sessions to a Capacitor server. Covers
coding-agent sessions (Claude Code, Codex, Cursor, Copilot, Gemini, Kiro,
Pi, OpenCode) to a Capacitor server. Covers
Comment thread
qodo-code-review[bot] marked this conversation as resolved.
install/setup/login, profiles, where its config and on-disk state live,
importing and remapping past sessions, recap/eval/errors on a recorded
session, visibility and privacy (hide, disable, ignoring or excluding
Expand All @@ -13,15 +14,15 @@ description: >-

# kcap CLI (Kurrent Capacitor)

`kcap` is the `@kurrent/kcap` npm CLI that records coding-agent sessions (Claude Code, Codex CLI, Cursor) to a Kurrent Capacitor server, then lets you recap, evaluate, and PR-review them with full transcript context. This skill is the source of truth for its commands, flags, config keys, and gotchas, the binary ships from a repo created after the model's training cutoff, so **do not reconstruct command or flag names from memory; copy them from the reference files.**
`kcap` is the `@kurrent/kcap` npm CLI that records coding-agent sessions (Claude Code, Codex CLI, Cursor, Copilot CLI, Gemini CLI, Kiro CLI, Pi, OpenCode) to a Kurrent Capacitor server, then lets you recap, evaluate, and PR-review them with full transcript context. This skill is the source of truth for its commands, flags, config keys, and gotchas, the binary ships from a repo created after the model's training cutoff, so **do not reconstruct command or flag names from memory; copy them from the reference files.**

## Overview

The CLI splits into a few concerns. Match the user's need to a reference file below and load only that one.

**Key surfaces:**

- **Onboarding**: `kcap setup` (one wizard: server URL, GitHub login, visibility, agent hooks, daemon name), then verify with `kcap status` / `kcap whoami`.
- **Onboarding**: `kcap setup` (one wizard: server URL, login via email/SSO or GitHub, visibility, agent hooks, daemon name), then verify with `kcap status` / `kcap whoami`.
- **Recording**: once an agent's hooks are installed, sessions stream automatically; nothing else to run.
- **Profiles**: one server config each (URL, visibility, daemon, ignore list); auto-switch by git remote.
- **History**: `kcap import` backfills past local transcripts; requires an explicit scope.
Expand All @@ -42,12 +43,16 @@ Pick the one file that owns the user's need. Don't load more than you need.
| Where the config file lives (`$HOME/.config/kcap/config.json`) and the `KCAP_CONFIG_DIR` override, `kcap config show` / `set`, config keys, default visibility, excluding repos vs paths (`excluded_repos` / `kcap ignore`), provider-API-key scrubbing, SessionStart guidance injection | [`references/config-privacy.md`](references/config-privacy.md) |
| `kcap daemon` lifecycle, running multiple daemons (naming / flock), hosted Claude/Codex agents, `daemon.claude_path` / `daemon.codex_path`, `kcap repos`, daemon env vars | [`references/daemon.md`](references/daemon.md) |
| Giving an agent session/PR context: `kcap mcp sessions` / `review` / `judge`, `kcap review <pr>`, auto-registration, the MCP tools | [`references/mcp-review.md`](references/mcp-review.md) |
| `kcap plugin install` / `remove` (hooks + skills) for Claude / Codex / Cursor, `--project` vs user scope, `--skills`, `--if-installed`, and `kcap uninstall` | [`references/plugins.md`](references/plugins.md) |
| `kcap plugin install` / `remove` (hooks + skills) for each supported agent (Claude, Codex, Cursor, Copilot, Gemini, Kiro, Pi, OpenCode), `--project` vs user scope, `--skills`, `--if-installed`, and `kcap uninstall` | [`references/plugins.md`](references/plugins.md) |

## Switching profiles

**Before running `kcap use` to switch profiles, ask whether to bind it to this repo only (the no-flag default) or globally (`--global`).** A no-flag `kcap use` silently creates a repo-scoped binding that overrides the global active profile for that directory, so choosing scope for the user can quietly reroute one repo while the rest stay on the old profile. Surface the choice; don't assume. See [`references/profiles.md`](references/profiles.md) for the binding mechanics and resolution order.

## Running the daemon persistently

**When the user wants the daemon to stay up (survive logout/reboot, restart on crash), recommend `kcap daemon service install` over `kcap daemon start -d`.** The detached `-d` form runs only until logout or reboot; the service form is OS-managed. See [`references/daemon.md`](references/daemon.md).

## Quick Reference

```bash
Expand Down
20 changes: 18 additions & 2 deletions plugins/kurrent/skills/kurrent-capacitor-cli/references/daemon.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,22 @@ kcap daemon doctor # diagnose lock-file state for every daemon
kcap daemon doctor --clean # also remove stale lock/pid files (held entries untouched)
```

Start options: `--name`, `--server-url`, `--max-agents <n>` (default 5), `--log-file <path>`, `-d`/`--detach`.
Start options: `--name`, `--server-url`, `--max-agents <n>` (default 5), `--log-file <path>`, `--log-level <trace|debug|information|warning|error|critical|none>` (default `information`; also via `KCAP_DAEMON_LOG_LEVEL`, the flag wins; use `debug` for transport diagnostics like DaemonPing RTT), `-d`/`--detach`.

## Run as an OS service

`kcap daemon service` registers the daemon as a per-user OS service (launchd on macOS, systemd user unit on Linux, Scheduled Task on Windows). A service-managed daemon survives logout, auto-restarts on crash/`SIGKILL`, and starts at login — unlike a manual `daemon start -d`, which runs only until logout/reboot.

```bash
kcap daemon service install # register + start; pins profile, captures PATH
kcap daemon service install --name laptop --profile work --max-agents 10 --no-start
kcap daemon service status # installed / running state
kcap daemon service start # start an installed (stopped) service
kcap daemon service stop # stop but keep installed
kcap daemon service uninstall # stop and remove the unit
```

`install` pins the profile via `KCAP_PROFILE` and captures your shell `PATH`, so `claude` / `codex` resolve the same way they do interactively. `--no-start` registers without starting. All actions take `--name N` to target a specific daemon name.

## Running multiple daemons on one machine

Expand Down Expand Up @@ -49,6 +64,7 @@ Runtime env-var overrides (take precedence over the profile):
```bash
KCAP_CLAUDE_PATH=/opt/claude/bin/claude kcap daemon start
KCAP_CODEX_PATH=/opt/codex/bin/codex kcap daemon start
KCAP_MAX_AGENTS=10 kcap daemon start # overrides --max-agents / daemon.max_agents
```

Hosted Codex agents require the Codex hook surface (installed by `kcap setup` or `kcap plugin install --codex`, see [plugins.md](plugins.md)). The daemon starts Codex with `--sandbox workspace-write` and `--ask-for-approval on-request`, escalating sensitive operations through the daemon's permission bridge to the dashboard.
Expand All @@ -70,5 +86,5 @@ Persisted to `~/.config/kcap/repos.json` and reported to the server on daemon co

```bash
kcap cleanup # kill all orphaned watcher processes
kcap update # check for and install CLI updates
kcap update # upgrade the CLI and refresh opted-in agent plugins (--check to only report)
```
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@

## Backfilling history

`kcap import` discovers and uploads past local transcripts from every detected agent so they appear in the dashboard:
`kcap import` discovers and uploads past local transcripts from every detected agent so they appear in the dashboard. It walks **seven** agents (`import` covers Claude, Codex, Cursor, Copilot, Gemini, Kiro, Pi; OpenCode is live-ingest only, no historical import):

- Claude, `~/.claude/projects/<encoded-cwd>/<sid>.jsonl`
- Codex, `~/.codex/sessions/.../rollout-<sid>.jsonl`
- Cursor, `~/.cursor/projects/<sanitized-workspace>/agent-transcripts/<sid>/<sid>.jsonl`
- Copilot, `~/.copilot/session-state/<sid>/events.jsonl` (honours `$COPILOT_HOME`)
- Gemini, `~/.gemini/tmp/<project>/chats/session-<ISO>-<shortId>.jsonl`
- Kiro, `~/.kiro/sessions/cli/<sid>.jsonl` (honours `$KIRO_HOME`)
- Pi, `~/.pi/agent/sessions/.../<timestamp>_<sid>.jsonl` (badlogic/pi-mono)

### A scope is REQUIRED

Expand All @@ -33,6 +37,8 @@ kcap import --codex --org # only Codex rollouts
kcap import --cursor --all # only Cursor
```

The full set of vendor filters: `--claude`, `--codex`, `--cursor`, `--copilot`, `--gemini`, `--kiro`, `--pi`. Filters are additive — pass several to import that subset.

### Other flags

```bash
Expand Down
Loading