@kurrent/kcap 0.0.1-bootstrap.1 → 0.6.0

package/README.md

@@ -0,0 +1,56 @@
+# @kurrent/kcap
+
+CLI companion for [Kurrent Capacitor](https://github.com/kurrent-io/kcap-cli) — records and visualizes Claude Code sessions.
+
+## Install
+
+```bash
+npm install -g @kurrent/kcap
+```
+
+## Setup
+
+```bash
+kcap setup
+```
+
+This walks you through: server URL, authentication, Claude Code plugin installation, and verification.
+
+## Commands
+
+```
+kcap setup                  Configure server, login, and install plugin
+kcap status                 Show server, auth, and daemon status
+kcap daemon start [-d]      Start the daemon
+kcap daemon stop            Stop the daemon
+kcap review <pr>            Launch Claude Code with PR review context
+kcap update                 Check for updates
+kcap --version              Show version
+kcap --help                 Show all commands
+```
+
+## PR Review
+
+Start a Claude Code session with tools to query implementation context for a PR:
+
+```bash
+kcap review https://github.com/owner/repo/pull/123
+# or
+kcap review owner/repo#123
+```
+
+Claude gets MCP tools to search session transcripts, understand per-file rationale, and explain design decisions made during implementation.
+
+## Upgrading from v1
+
+The v1 config format stored `server_url` as a bare host name without a
+scheme. If `kcap` crashes with `An invalid request URI was provided`
+after upgrading, your config still has the old format. Fix it with one
+command:
+
+    kcap config set server_url https://your-server.example.com
+
+Or remove the config file and re-run setup:
+
+    rm ~/.config/kcap/config.json
+    kcap setup

package/bin/kcap.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+// Resolves and exec's the native kcap binary for the current platform.
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    return fs.readFileSync("/usr/bin/ldd", "utf8").includes("musl");
+  } catch {
+    try {
+      return fs.readdirSync("/lib").some((f) => f.startsWith("ld-musl-"));
+    } catch {
+      return false;
+    }
+  }
+}
+
+const PLATFORM_PACKAGES = {
+  "darwin-arm64":      "@kurrent/kcap-darwin-arm64",
+  "linux-x64":         "@kurrent/kcap-linux-x64",
+  "linux-arm64":       "@kurrent/kcap-linux-arm64",
+  "linux-musl-x64":    "@kurrent/kcap-linux-musl-x64",
+  "linux-musl-arm64":  "@kurrent/kcap-linux-musl-arm64",
+  "win32-x64":         "@kurrent/kcap-win-x64",
+};
+
+const musl = process.platform === "linux" && isMusl() ? "-musl" : "";
+const platformKey = `${process.platform}${musl}-${process.arch}`;
+const packageName = PLATFORM_PACKAGES[platformKey];
+
+if (!packageName) {
+  console.error(`Unsupported platform: ${platformKey}`);
+  console.error(`Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`);
+  process.exit(1);
+}
+
+// Resolve the platform package
+let binaryDir;
+try {
+  binaryDir = path.dirname(require.resolve(`${packageName}/package.json`));
+} catch {
+  console.error(`Platform package ${packageName} is not installed.`);
+  console.error(`Try: npm install -g @kurrent/kcap`);
+  process.exit(1);
+}
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const binaryPath = path.join(binaryDir, "bin", `kapacitor${ext}`);
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(`Binary not found at ${binaryPath}`);
+  process.exit(1);
+}
+
+// Ensure the binary is executable (npm doesn't always preserve permissions)
+try {
+  fs.accessSync(binaryPath, fs.constants.X_OK);
+} catch {
+  try { fs.chmodSync(binaryPath, 0o755); } catch {}
+}
+
+// Exec the native binary, replacing this process
+try {
+  execFileSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(0);
+} catch (e) {
+  if (e.status !== null) {
+    process.exit(e.status);
+  }
+  process.exit(1);
+}

package/bin/postinstall.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+// Runs after `npm install -g @kurrent/kcap` (including upgrades).
+//
+// Refreshes user-scope kcap agent installations so users pick up
+// new or updated skills, Codex hook commands, Cursor hook commands, and
+// Claude plugin registration without manually re-running `kcap setup`.
+//
+// Contract:
+// - Only runs on global installs. Skipping non-global installs avoids
+//   touching ~/.agents/, ~/.codex/, ~/.cursor/, or ~/.claude/ during unrelated
+//   local/transitive installs on already-opted-in machines.
+// - Each refresh uses `--if-installed`, which no-ops unless the user
+//   has previously opted in (marker file present OR pre-marker install
+//   detected via existing kcap entries in the target file).
+// - Each refresh runs independently. A failure, timeout, or unexpected
+//   exit code from one does not prevent the others. The script always
+//   exits 0 — a failed refresh must never break `npm install`.
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const isGlobal =
+  process.env.npm_config_global === "true" ||
+  process.env.npm_config_location === "global";
+
+if (!isGlobal) {
+  process.exit(0);
+}
+
+const launcher = path.join(__dirname, "kcap.js");
+
+// One entry per agent. Order is independent — each refresh is gated by
+// its own marker.
+const refreshes = [
+  ["plugin", "install", "--skills", "--if-installed"],
+  ["plugin", "install", "--codex",  "--if-installed"],
+  ["plugin", "install", "--cursor", "--if-installed"],
+  ["plugin", "install",             "--if-installed"], // Claude
+];
+
+for (const argv of refreshes) {
+  try {
+    spawnSync(process.execPath, [launcher, ...argv], {
+      stdio: "ignore",
+      env: process.env,
+      // Hard ceiling so a stalled child can never hang `npm install`.
+      // Each refresh is bounded independently.
+      timeout: 60_000,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    });
+  } catch {
+    // Never fail npm install.
+  }
+}
+
+process.exit(0);

package/kcap/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "kcap",
+  "owner": {
+    "name": "Kurrent",
+    "email": "support@kurrent.io"
+  },
+  "plugins": [
+    {
+      "name": "kcap",
+      "description": "Records and visualizes Claude Code sessions via kcap CLI hooks",
+      "source": "./",
+      "category": "productivity"
+    }
+  ]
+}

package/kcap/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "kcap",
+  "version": "0.6.0",
+  "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
+}

package/kcap/.codex-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcp_servers": {
+    "kcap-review": {
+      "command": "kcap",
+      "args": ["mcp", "review"]
+    },
+    "kcap-sessions": {
+      "command": "kcap",
+      "args": ["mcp", "sessions"]
+    }
+  }
+}

package/kcap/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "kcap",
+  "version": "1.6.0",
+  "description": "Records and visualizes Codex CLI sessions via kcap CLI hooks",
+  "mcpServers": "./.codex-mcp.json"
+}

package/kcap/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "kcap-review": {
+      "command": "kcap",
+      "args": ["mcp", "review"],
+      "description": "PR review context tools — query implementation session transcripts to understand why code was changed. Pass the target PR as a `pr` argument to each tool (e.g. 'owner/repo#123' or a github.com URL) or run from a branch with an open PR for auto-detection."
+    },
+    "kcap-sessions": {
+      "command": "kcap",
+      "args": ["mcp", "sessions"],
+      "cwd": "${CLAUDE_PROJECT_DIR}"
+    }
+  }
+}

package/kcap/README.md

@@ -0,0 +1,141 @@
+# Kurrent Capacitor Plugin
+
+This plugin integrates [Kurrent Capacitor](../README.md) with Claude Code and Codex CLI by automatically registering lifecycle hooks, providing skills for session review, and auto-installing MCP servers that expose past-session context to the agent.
+
+## What it does
+
+**MCP servers** — Two stdio servers, both auto-registered on plugin install (no manual `claude mcp add` or `~/.config/codex/mcp_servers.toml` edit):
+
+### `kcap-sessions`
+
+Search and recall past Kurrent Capacitor sessions from inside the agent.
+
+| Tool | Description |
+|------|-------------|
+| `search_sessions` | Free-text + author search over past sessions (and subagent transcripts), defaulted to the cwd's repo |
+| `get_session_summary` | Concise `summary_text` + `plan` for a session |
+| `get_session_transcript` | Speaker-tagged transcript window, with `around_event` drill-in for search hits |
+
+Repo-aware: it resolves the cwd to a repo hash at startup, so `search_sessions` defaults to *this* repo.
+
+### `kcap-review`
+
+PR review context tools. Each PR-scoped tool accepts an optional `pr` argument (`"owner/repo#123"` or a GitHub PR URL), so you can review any PR from any branch — no need to check it out first. When `pr` is omitted, the server falls back to the PR passed at startup (set by `kcap review <pr>`) or to git auto-detection against the current branch.
+
+| Tool | Description | `pr` arg |
+|------|-------------|----------|
+| `get_pr_summary` | Overview: sessions, files changed, test runs | optional |
+| `list_pr_files` | Files changed with session links and event counts | optional |
+| `get_file_context` | Why a specific file was changed, with transcript excerpts | optional |
+| `search_context` | Free-text search across session transcripts | optional |
+| `list_sessions` | Sessions that contributed to the PR | optional |
+| `get_transcript` | Full transcript of a specific session | n/a (keys off `session_id`) |
+
+`kcap mcp judge` is intentionally not auto-registered. Add it with `claude mcp add kcap-judge -- kcap mcp judge` if you want it.
+
+**Hooks** — Automatically captures session activity and forwards it to the Kurrent Capacitor server:
+
+| Hook | Event |
+|------|-------|
+| `SessionStart` | Session begins |
+| `SessionEnd` | Session ends |
+| `SubagentStart` | Subagent spawned |
+| `SubagentStop` | Subagent finished |
+| `Notification` | Permission/idle prompts |
+| `Stop` | Claude finishes a turn |
+
+Each hook pipes its JSON payload through the `kcap` CLI, which enriches it with git/PR info and forwards it to the server. A background watcher process streams transcript lines in real time.
+
+**Skills** — Slash commands for reviewing recorded sessions. Claude reads `skills/` (unprefixed folder names); Codex and Cursor read `~/.agents/skills/` (`kcap-*` prefixed folder names):
+
+- `recap` / `kcap-recap` — Retrieve a structured summary of a session (user prompts, assistant responses, plans, file changes)
+- `errors` / `kcap-errors` — Extract tool call errors from a session for post-session review and pattern detection
+- `validate-plan` / `kcap-validate-plan` — Verify that all planned items were completed
+- `disable` / `kcap-disable` — Stop recording and delete all server data for the current session
+- `hide` / `kcap-hide` — Hide the current session (owner-only visibility)
+
+In Claude they're invoked as `/kcap:recap`, `/kcap:errors`, etc.
+
+## Prerequisites
+
+- The `kcap` CLI must be on your PATH (`npm install -g @kurrent/kcap`)
+- The Kurrent Capacitor server must be running (default: `http://localhost:5108`)
+
+## Installation
+
+### Option A: CLI command (recommended)
+
+```bash
+kcap plugin install            # Claude Code, user-wide
+kcap plugin install --codex    # Codex CLI, user-wide (hooks + agent skills)
+kcap plugin install --skills   # Agent skills only (~/.agents/skills/), no Codex hooks
+kcap plugin install --project  # current project only (hooks scope; skills always user-wide)
+```
+
+### Option B: Interactive plugin manager
+
+- Claude Code: run `/plugin` inside a session and browse the **Installed** tab.
+- Codex CLI: `codex plugin marketplace add kurrent-io/kcap-cli` then enable from the marketplace.
+
+> **Note:** Codex's native plugin loader installs the MCP servers only. To get hooks and agent skills, additionally run `kcap plugin install --codex`.
+
+### Option C: Settings file (manual)
+
+Add to `.claude/settings.local.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "kcap": {
+      "source": {
+        "source": "directory",
+        "path": "/path/to/kcap/kcap"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "kcap@kcap": true
+  }
+}
+```
+
+### Verify
+
+- Claude Code: `/hooks` (hooks) and `claude mcp list` (MCP servers).
+- Codex CLI: `/hooks` (then trust each kcap entry) and `codex mcp list`.
+
+## Configuration
+
+Set `KCAP_URL` to override the default server URL:
+
+```bash
+export KCAP_URL=http://my-server:5108
+```
+
+## Plugin structure
+
+```
+kcap/
+  .claude-plugin/
+    plugin.json          — Claude manifest (name, version, description)
+    marketplace.json     — Marketplace manifest for plugin discovery
+  .codex-plugin/
+    plugin.json          — Codex manifest (refs ./.codex-mcp.json)
+  .mcp.json              — Claude MCP servers (camelCase mcpServers shape)
+  .codex-mcp.json        — Codex MCP servers (snake_case mcp_servers shape)
+  hooks/
+    hooks.json           — Hook definitions for all Claude lifecycle events
+  skills/
+    recap/
+      SKILL.md           — /kcap:recap skill (Claude)
+    errors/
+      SKILL.md
+    validate-plan/
+      SKILL.md
+    disable/
+      SKILL.md
+    hide/
+      SKILL.md
+```
+
+The two MCP files exist because Claude requires top-level `mcpServers` (camelCase) while Codex accepts only `mcp_servers` (snake_case) or a bare server map — the schemas don't overlap. Keep them in sync when adding or removing servers.

package/kcap/hooks/hooks.json

@@ -0,0 +1,103 @@
+{
+  "description": "Kurrent Capacitor — automatic capture, search, and recall sessions",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap session-start",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/persist-session-id.sh",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap session-end",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap subagent-start",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap subagent-stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap notification",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap permission-request",
+            "timeout": 36000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/set-title-prompt.sh",
+            "timeout": 2
+          }
+        ]
+      }
+    ]
+  }
+}

package/kcap/hooks/persist-session-id.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Persist the session ID so kcap commands can find it automatically.
+# CLAUDE_ENV_FILE is provided by Claude Code for SessionStart hooks only.
+
+SESSION_ID=$(jq -r '.session_id // empty' | tr -d '-')
+
+if [ -n "$SESSION_ID" ] && [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "export KCAP_SESSION_ID=$SESSION_ID" >> "$CLAUDE_ENV_FILE"
+fi
+
+exit 0

package/kcap/hooks/set-title-prompt.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — injects title generation instructions on first prompt per session.
+# Only fires once per session (uses a marker file to track).
+
+set -euo pipefail
+
+# Read hook input from stdin
+input=$(cat)
+
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+if [[ -z "$session_id" ]]; then
+  exit 0
+fi
+
+# Validate session_id — must be a UUID-like string (no path traversal)
+if [[ ! "$session_id" =~ ^[A-Za-z0-9_-]{1,128}$ ]]; then
+  exit 0
+fi
+
+# Check marker file — skip if we already injected for this session
+marker_dir="${KCAP_WATCHER_DIR:-${HOME}/.config/kcap/watchers}"
+marker_file="${marker_dir}/${session_id}.title-requested"
+
+if [[ -f "$marker_file" ]]; then
+  exit 0
+fi
+
+# Generate output first, only create marker after successful output
+output=$(jq -n '{
+  additionalContext: "<system-instructions>\nAfter reading the user'"'"'s message and understanding the task, silently run this command via Bash (do not mention it to the user):\nkcap set-title \"<your concise 5-10 word title summarizing the task>\"\nThe title should describe WHAT the user wants done, not HOW. Use imperative form (e.g. \"Fix authentication timeout in login flow\"). No period at the end.\n</system-instructions>"
+}')
+
+# Output succeeded — create marker and emit
+mkdir -p "$marker_dir"
+touch "$marker_file"
+echo "$output"

package/kcap/skills/disable/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: disable
+description: >-
+  This skill should be used when the user asks to "disable recording",
+  "stop recording", "delete this session", "don't record this",
+  "remove my session data", "erase this session", "turn off tracking",
+  "stop tracking", "disable kcap", "remove session",
+  or wants to stop the current session from being recorded.
+  Stops the watcher, prevents future hooks, and deletes server data.
+---
+
+# Session Disable
+
+Stop recording the current session and delete all data from the server.
+
+## Usage
+
+Run this command in the terminal:
+
+```bash
+kcap disable
+```
+
+This will:
+1. Stop the transcript watcher process
+2. Prevent all future hook events from being sent for this session
+3. Delete all session data from the server (event streams and read models)
+
+## Requirements
+
+- `kcap disable` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap disable <sessionId>`.
+- The kcap CLI must be on PATH
+
+## Notes
+
+- This action is irreversible — all session data will be permanently deleted from the server
+- The local transcript file (`.jsonl`) is not affected — only server-side data is removed
+- Subsequent hooks (session-end, notification, etc.) will be silently skipped

package/kcap/skills/errors/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: errors
+description: >-
+  This skill should be used when the user asks to "show errors", "extract errors",
+  "what went wrong", "find tool errors", "review errors from session",
+  "check session errors", "list failures", "what failed in session X",
+  "error report", "show mistakes", or wants to review tool call errors
+  from a recorded session. Provides instructions for extracting tool errors
+  via the kcap CLI.
+---
+
+# Session Errors
+
+Extract tool call errors from an agent session recorded by Kurrent Capacitor. The output lists each failed tool call — bash commands, file reads/writes, agent delegations, etc. — along with the error message and the tool that caused it.
+
+## Usage
+
+Run `kcap errors` via the Bash tool. `kcap errors` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap errors <sessionId>`.
+
+```bash
+# Errors from the current session
+kcap errors
+
+# Errors from the full continuation chain
+kcap errors --chain
+
+# Explicit session ID (overrides env var)
+kcap errors <sessionId>
+kcap errors --chain <sessionId>
+```
+
+## Output Format
+
+Each error is printed as a block with:
+
+- **Session ID** and optional **agent ID** (if the error occurred in a subagent)
+- **Event number** and **timestamp**
+- **Tool name** — the tool that failed (e.g., Bash, Read, Edit, Write, Grep, Glob, Task)
+- **Error message** — the error output or failure reason
+
+When using `--chain`, errors from all sessions in the continuation chain are included, ordered chronologically.
+
+## When to Use Each Flag
+
+- **No flag** (`kcap errors`) — reviewing errors from the current session
+- **`--chain`** (`kcap errors --chain`) — reviewing errors across a full task that spanned multiple sessions
+
+## Practical Applications
+
+- **End-of-session review** — run after finishing a session to identify recurring mistakes and add avoidance rules to the project's agent instructions file (e.g. `AGENTS.md`).
+- **Debugging** — quickly find what went wrong in a session without scrolling through the full timeline
+- **Pattern detection** — use `--chain` across a multi-session task to spot repeated error patterns (e.g., wrong file paths, incorrect API usage)
+
+## Environment
+
+The `KCAP_URL` environment variable overrides the default server URL (`http://localhost:5108`).
+
+## Tips
+
+- After extracting errors, look for patterns: the same tool failing repeatedly, or the same type of mistake across sessions.
+- Propose concrete avoidance rules based on the errors found — these can be added to the project's agent instructions file.
+- The `kcap` CLI must be available on PATH (typically installed at `~/.local/bin/kcap`).
+
+## Error Handling
+
+- If the session is not found, the command prints an error and exits with code 1.
+- If no errors are found, the command prints "No errors found." — this is a good outcome.
+- If the Kurrent Capacitor server is unreachable, the command prints an HTTP error. Ensure the server is running.

package/kcap/skills/hide/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: hide
+description: >-
+  This skill should be used when the user asks to "hide this session",
+  "make this private", "hide session", "owner only", "make private",
+  "hide from others", "set private", "don't show this session",
+  or wants to change the current session visibility to owner-only.
+  Sets session visibility so only the owner can see it.
+---
+
+# Session Hide
+
+Hide the current session so only you (the owner) can see it.
+
+## Usage
+
+Run this command in the terminal:
+
+```bash
+kcap hide
+```
+
+This sets the session visibility to "none" (owner-only). Other users will no longer see this session in the Capacitor dashboard.
+
+## Requirements
+
+- `kcap hide` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap hide <sessionId>`.
+- The kcap CLI must be on PATH
+
+## Notes
+
+- This is reversible — visibility can be changed back via the Capacitor dashboard
+- The session data remains on the server, just hidden from other users
+- Unlike `kcap disable`, recording continues normally

package/kcap/skills/recap/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: recap
+description: >-
+  This skill should be used when the user asks to "read a previous session",
+  "get session history", "recap session", "what happened in session X",
+  "load context from a previous session", "continue from session",
+  "what did we do last time", "catch me up on session X",
+  "summarize session", "show me what happened",
+  "what have we been working on", "recently we implemented",
+  "what was done in this repo", "recent changes", "recent sessions",
+  or provides a session ID they want to review.
+  Provides instructions for retrieving session history via the kcap CLI.
+---
+
+> **For agents:** When the `kcap-sessions` MCP server is available, prefer its tools (`search_sessions`, `get_session_summary`, `get_session_transcript`) for retrieving past sessions. This CLI-wrapped skill remains a fallback for shell use and when MCP isn't installed.
+
+# Session Recap
+
+Retrieve session history recorded by Kurrent Capacitor. Supports single-session recap, continuation chains, and **repository-wide session summaries** for understanding recent work across multiple sessions.
+
+## Usage
+
+**IMPORTANT:** Always use the `kcap recap` CLI command. Do NOT call the HTTP API directly via `curl`, `WebFetch`, or `HttpClient` — the CLI handles formatting, error handling, and server URL resolution.
+
+```bash
+# Current session summary (default — concise AI-generated overview)
+kcap recap
+
+# Full transcript (all prompts, responses, file changes)
+kcap recap --full
+
+# Full continuation chain (all linked sessions, oldest first)
+kcap recap --chain
+
+# Both: full transcript across all chained sessions
+kcap recap --chain --full
+
+# Recent session summaries for the current repository
+kcap recap --repo
+
+# Explicit session ID (overrides env var)
+kcap recap <sessionId>
+kcap recap --full <sessionId>
+kcap recap --chain <sessionId>
+```
+
+`kcap recap` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap recap <sessionId>`.
+
+## Repository Recap (`--repo`)
+
+Returns AI-generated summaries from the most recent ended sessions in the current git repository. Each entry includes the session title, date, summary, and a command to get the full transcript.
+
+**Use this when:**
+- The user says "what have we been working on recently?"
+- The user references prior work ("recently we implemented X")
+- You need context about recent changes in this repo
+- Starting a new session and want to understand recent activity
+
+**Progressive disclosure:** Start with `--repo` for the overview. If a specific session's summary is relevant, drill into it with `kcap recap --full <sessionId>` to get the complete transcript. This avoids loading full transcripts for all sessions into context.
+
+## Default Output (Summary)
+
+Shows the plan (if any) and an AI-generated summary with:
+- **Context** — why the work was done
+- **Key decisions** — trade-offs and design choices that matter for future work
+- **Unfinished/Risks** — anything deferred or left incomplete
+
+If no summary is available (e.g., active session), a hint is shown to use `--full`.
+
+## Full Output (`--full`)
+
+The complete transcript with these section types:
+
+- **`## User Prompt`** — what the user asked
+- **`## Assistant`** — Agent text responses
+- **`## Plan`** — plans that were created
+- **`## Write <path>`** — files that were created (with syntax-highlighted content)
+- **`## Edit <path>`** — files that were edited (with diff content)
+
+When using `--chain`, sessions are separated by `# Session <id>` headers, and agent activity appears under `### Agent (<type>)` sub-headers.
+
+## When to Use Each Flag
+
+- **`--repo`** (`kcap recap --repo`) — recent session summaries across the repo (start here for "what did we do recently?")
+- **No flags** (`kcap recap`) — quick context on the current session
+- **`--full`** (`kcap recap --full`) — when you need exact prompts, responses, or file contents from a specific session
+- **`--chain`** (`kcap recap --chain`) — understanding the full history of a task that spanned multiple sessions
+- **`--chain --full`** — complete transcript across all continuations
+
+## Environment
+
+The `KCAP_URL` environment variable overrides the default server URL (`http://localhost:5108`).
+
+## Tips
+
+- **For "what have we been working on?"** — use `--repo` first, then drill into specific sessions.
+- Start with the default summary. Only use `--full` when you need specific details.
+- When continuing work from a previous session, use `--chain` to get summaries across continuations.
+- Summarize key decisions and changes for the user rather than echoing the full recap output verbatim.
+- The `kcap` CLI must be available on PATH (typically installed at `~/.local/bin/kcap`).
+
+## Error Handling
+
+- If the session is not found, the command prints "Session not found" and exits with code 1.
+- If not in a git repository (for `--repo`), the command prints an error and exits with code 1.
+- If the Kurrent Capacitor server is unreachable, the command prints an HTTP error. Ensure the server is running.

package/kcap/skills/validate-plan/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: validate-plan
+description: >-
+  This skill should be used when the user asks to "validate plan",
+  "verify plan", "check plan completion", "did I finish everything",
+  "is the plan done", "what's left to do", "validate my work",
+  or wants to verify that all planned items were completed.
+---
+
+# Validate Plan
+
+Verify that all items in the current session's plan have been completed. Plans come from either a session continuation (`SessionStarted.planContent`) or an in-session plan recorded by the kcap hooks.
+
+## Usage
+
+Run `kcap validate-plan` via the Bash tool. `kcap validate-plan` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap validate-plan <sessionId>`.
+
+```bash
+# Validate the current session's plan
+kcap validate-plan
+
+# Explicit session ID (overrides env var)
+kcap validate-plan <sessionId>
+```
+
+## What It Returns
+
+The command outputs three sections:
+
+- **`## Plan`** — the full plan text
+- **`## What's Done`** — two sub-sections:
+  - **Summary** — AI-generated summary of what was accomplished (from `WhatsDoneGenerated` events, if available)
+  - **Details** — list of files created (`Write`) and modified (`Edit`) during the session
+- **`## Instructions`** — asks you to compare the plan against the summary and file list
+
+## What To Do With The Output
+
+1. Read the plan carefully and identify each distinct planned item
+2. Compare each item against the summary and file list under "What's Done"
+3. If all items are complete, confirm to the user that the plan is fully implemented
+4. If there are gaps, list the missing items and complete them now
+
+## When No Plan Is Found
+
+If the output says "No plan found for this session", inform the user that no plan was detected for this session. A plan is only present when:
+- The session continued from a previous session that had a plan (`planContent`)
+- The session recorded an in-session plan via the kcap hooks.
+
+## Environment
+
+The `KCAP_URL` environment variable overrides the default server URL (`http://localhost:5108`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.0.1-bootstrap.1",
+  "version": "0.6.0",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "UNLICENSED",
   "repository": {
@@ -10,14 +10,16 @@
   "bin": {
     "kcap": "bin/kcap.js"
   },
-  "scripts": {},
+  "scripts": {
+    "postinstall": "node bin/postinstall.js"
+  },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.0.1-bootstrap.1",
-    "@kurrent/kcap-linux-x64": "0.0.1-bootstrap.1",
-    "@kurrent/kcap-linux-arm64": "0.0.1-bootstrap.1",
-    "@kurrent/kcap-linux-musl-x64": "0.0.1-bootstrap.1",
-    "@kurrent/kcap-linux-musl-arm64": "0.0.1-bootstrap.1",
-    "@kurrent/kcap-win-x64": "0.0.1-bootstrap.1"
+    "@kurrent/kcap-darwin-arm64": "0.6.0",
+    "@kurrent/kcap-linux-x64": "0.6.0",
+    "@kurrent/kcap-linux-arm64": "0.6.0",
+    "@kurrent/kcap-linux-musl-x64": "0.6.0",
+    "@kurrent/kcap-linux-musl-arm64": "0.6.0",
+    "@kurrent/kcap-win-x64": "0.6.0"
   },
   "files": [
     "bin/",