@kurrent/kapacitor 0.4.9 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @kurrent/kapacitor
|
|
2
2
|
|
|
3
|
-
CLI companion for [Kurrent Capacitor](https://github.com/kurrent-io/kapacitor) — records and visualizes Claude Code sessions.
|
|
3
|
+
CLI companion for [Kurrent Capacitor](https://github.com/kurrent-io/kapacitor-cli) — records and visualizes Claude Code sessions.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -20,9 +20,9 @@ This walks you through: server URL, authentication, Claude Code plugin installat
|
|
|
20
20
|
|
|
21
21
|
```
|
|
22
22
|
kapacitor setup Configure server, login, and install plugin
|
|
23
|
-
kapacitor status Show server, auth, and
|
|
24
|
-
kapacitor
|
|
25
|
-
kapacitor
|
|
23
|
+
kapacitor status Show server, auth, and daemon status
|
|
24
|
+
kapacitor daemon start [-d] Start the daemon
|
|
25
|
+
kapacitor daemon stop Stop the daemon
|
|
26
26
|
kapacitor review <pr> Launch Claude Code with PR review context
|
|
27
27
|
kapacitor update Check for updates
|
|
28
28
|
kapacitor --version Show version
|
|
@@ -40,3 +40,17 @@ kapacitor review owner/repo#123
|
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
Claude gets MCP tools to search session transcripts, understand per-file rationale, and explain design decisions made during implementation.
|
|
43
|
+
|
|
44
|
+
## Upgrading from v1
|
|
45
|
+
|
|
46
|
+
The v1 config format stored `server_url` as a bare host name without a
|
|
47
|
+
scheme. If `kapacitor` crashes with `An invalid request URI was provided`
|
|
48
|
+
after upgrading, your config still has the old format. Fix it with one
|
|
49
|
+
command:
|
|
50
|
+
|
|
51
|
+
kapacitor config set server_url https://your-server.example.com
|
|
52
|
+
|
|
53
|
+
Or remove the config file and re-run setup:
|
|
54
|
+
|
|
55
|
+
rm ~/.config/kapacitor/config.json
|
|
56
|
+
kapacitor setup
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kapacitor-errors
|
|
3
|
+
description: >-
|
|
4
|
+
Use when the user asks to "show errors", "extract errors", "what went wrong",
|
|
5
|
+
"find tool errors", "review errors from session", "check session errors",
|
|
6
|
+
"list failures", "what failed in session X", "error report", "show mistakes",
|
|
7
|
+
or wants to review tool call errors from a recorded session. Extracts tool
|
|
8
|
+
errors via the `kapacitor errors` CLI.
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Kapacitor Errors
|
|
12
|
+
|
|
13
|
+
Extract tool call errors from a session recorded by Kurrent Capacitor. The output lists each failed tool call — shell commands, file reads/writes, agent delegations, etc. — along with the error message and the tool that caused it.
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
Codex sessions do not export `KAPACITOR_SESSION_ID`, so you must pass the session ID explicitly. To find recent session IDs, run `kapacitor recap --repo` first.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Errors from a specific session
|
|
21
|
+
kapacitor errors <sessionId>
|
|
22
|
+
|
|
23
|
+
# Errors from the full continuation chain starting at a session
|
|
24
|
+
kapacitor errors --chain <sessionId>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Output Format
|
|
28
|
+
|
|
29
|
+
Each error is printed as a block with:
|
|
30
|
+
|
|
31
|
+
- **Session ID** and optional **agent ID** (if the error occurred in a subagent)
|
|
32
|
+
- **Event number** and **timestamp**
|
|
33
|
+
- **Tool name** — the tool that failed (e.g., Bash, Read, Edit, Write, Grep, Glob)
|
|
34
|
+
- **Error message** — the error output or failure reason
|
|
35
|
+
|
|
36
|
+
When using `--chain`, errors from all sessions in the continuation chain are included, ordered chronologically.
|
|
37
|
+
|
|
38
|
+
## When to Use Each Flag
|
|
39
|
+
|
|
40
|
+
- **No flag** (`kapacitor errors <sessionId>`) — reviewing errors from one specific session
|
|
41
|
+
- **`--chain <sessionId>`** — reviewing errors across a full task that spanned multiple sessions
|
|
42
|
+
|
|
43
|
+
## Practical Applications
|
|
44
|
+
|
|
45
|
+
- **Post-mortem review** — after finishing a session, identify recurring mistakes and update project rules (CLAUDE.md / AGENTS.md) with avoidance guidance.
|
|
46
|
+
- **Debugging** — quickly find what went wrong in a session without scrolling through the full timeline.
|
|
47
|
+
- **Pattern detection** — use `--chain` across a multi-session task to spot repeated error patterns (e.g., wrong file paths, incorrect API usage).
|
|
48
|
+
|
|
49
|
+
## Environment
|
|
50
|
+
|
|
51
|
+
`KAPACITOR_URL` overrides the default server URL (`http://localhost:5108`).
|
|
52
|
+
|
|
53
|
+
## Tips
|
|
54
|
+
|
|
55
|
+
- After extracting errors, look for patterns: the same tool failing repeatedly, or the same type of mistake across sessions.
|
|
56
|
+
- Propose concrete avoidance rules based on the errors found — these can be added to AGENTS.md / CLAUDE.md.
|
|
57
|
+
- The `kapacitor` CLI must be available on PATH (typically installed at `~/.local/bin/kapacitor`).
|
|
58
|
+
|
|
59
|
+
## Error Handling
|
|
60
|
+
|
|
61
|
+
- If the session is not found, the command prints an error and exits with code 1.
|
|
62
|
+
- If no errors are found, the command prints "No errors found." — this is a good outcome.
|
|
63
|
+
- If the Kurrent Capacitor server is unreachable, the command prints an HTTP error. Ensure the server is running.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kapacitor-recap
|
|
3
|
+
description: >-
|
|
4
|
+
Use when the user asks to "read a previous session", "get session history",
|
|
5
|
+
"recap session", "what happened in session X", "load context from a previous
|
|
6
|
+
session", "continue from session", "what did we do last time", "catch me up",
|
|
7
|
+
"summarize session", "what have we been working on", "recent changes",
|
|
8
|
+
"recent sessions", or references prior work in this repo. Retrieves session
|
|
9
|
+
summaries recorded by Kurrent Capacitor via the `kapacitor recap` CLI.
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Kapacitor Recap
|
|
13
|
+
|
|
14
|
+
Retrieve session history recorded by Kurrent Capacitor. Inside Codex, the recommended entry point is the **repository recap** — Codex sessions do not export a `KAPACITOR_SESSION_ID` environment variable, so the "current session" shortcut is unavailable. Drill into a specific session by passing its ID explicitly.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
Run the `kapacitor recap` CLI via the shell. Do NOT call the HTTP API directly — the CLI handles formatting, error handling, and server URL resolution.
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Recent session summaries for the current repository (start here)
|
|
22
|
+
kapacitor recap --repo
|
|
23
|
+
|
|
24
|
+
# Drill into a specific session by ID (from --repo output)
|
|
25
|
+
kapacitor recap <sessionId>
|
|
26
|
+
|
|
27
|
+
# Full transcript for a specific session
|
|
28
|
+
kapacitor recap --full <sessionId>
|
|
29
|
+
|
|
30
|
+
# Full continuation chain (all linked sessions, oldest first)
|
|
31
|
+
kapacitor recap --chain <sessionId>
|
|
32
|
+
|
|
33
|
+
# Both: full transcript across all chained sessions
|
|
34
|
+
kapacitor recap --chain --full <sessionId>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Repository Recap (`--repo`)
|
|
38
|
+
|
|
39
|
+
Returns AI-generated summaries from the most recent ended sessions in the current git repository. Each entry includes the session title, date, summary, and the session ID needed to drill in further.
|
|
40
|
+
|
|
41
|
+
**Use this when:**
|
|
42
|
+
- The user says "what have we been working on recently?"
|
|
43
|
+
- The user references prior work ("recently we implemented X")
|
|
44
|
+
- You need context about recent changes in this repo
|
|
45
|
+
- Starting a new session and want to understand recent activity
|
|
46
|
+
|
|
47
|
+
**Progressive disclosure:** Start with `--repo` for the overview. If a specific session's summary is relevant, drill into it with `kapacitor recap --full <sessionId>` to get the complete transcript. This avoids loading full transcripts for all sessions into context.
|
|
48
|
+
|
|
49
|
+
## Session Recap (`<sessionId>`)
|
|
50
|
+
|
|
51
|
+
Shows the plan (if any) and an AI-generated summary with:
|
|
52
|
+
- **Context** — why the work was done
|
|
53
|
+
- **Key decisions** — trade-offs and design choices that matter for future work
|
|
54
|
+
- **Unfinished/Risks** — anything deferred or left incomplete
|
|
55
|
+
|
|
56
|
+
If no summary is available (e.g., active session), a hint is shown to use `--full`.
|
|
57
|
+
|
|
58
|
+
## Full Output (`--full`)
|
|
59
|
+
|
|
60
|
+
The complete transcript with these section types:
|
|
61
|
+
|
|
62
|
+
- **`## User Prompt`** — what the user asked
|
|
63
|
+
- **`## Assistant`** — text responses
|
|
64
|
+
- **`## Plan`** — plans that were created (Claude Code sessions only)
|
|
65
|
+
- **`## Write <path>`** — files that were created (with syntax-highlighted content)
|
|
66
|
+
- **`## Edit <path>`** — files that were edited (with diff content)
|
|
67
|
+
|
|
68
|
+
When using `--chain`, sessions are separated by `# Session <id>` headers, and agent activity appears under `### Agent (<type>)` sub-headers.
|
|
69
|
+
|
|
70
|
+
## When to Use Each Flag
|
|
71
|
+
|
|
72
|
+
- **`--repo`** — recent session summaries across the repo (start here)
|
|
73
|
+
- **`<sessionId>`** — quick context on a specific session (from `--repo` output)
|
|
74
|
+
- **`--full <sessionId>`** — when you need exact prompts, responses, or file contents
|
|
75
|
+
- **`--chain <sessionId>`** — understanding the full history of a task that spanned multiple sessions
|
|
76
|
+
- **`--chain --full <sessionId>`** — complete transcript across all continuations
|
|
77
|
+
|
|
78
|
+
## Environment
|
|
79
|
+
|
|
80
|
+
`KAPACITOR_URL` overrides the default server URL (`http://localhost:5108`).
|
|
81
|
+
|
|
82
|
+
## Tips
|
|
83
|
+
|
|
84
|
+
- Always start with `--repo` — it gives the overview without flooding context.
|
|
85
|
+
- Summarize key decisions and changes for the user rather than echoing the full recap output verbatim.
|
|
86
|
+
- The `kapacitor` CLI must be available on PATH (typically installed at `~/.local/bin/kapacitor`).
|
|
87
|
+
|
|
88
|
+
## Error Handling
|
|
89
|
+
|
|
90
|
+
- If the session is not found, the command prints "Session not found" and exits with code 1.
|
|
91
|
+
- If not in a git repository (for `--repo`), the command prints an error and exits with code 1.
|
|
92
|
+
- If the Kurrent Capacitor server is unreachable, the command prints an HTTP error. Ensure the server is running.
|
package/package.json
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kurrent/kapacitor",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"bin": {
|
|
7
7
|
"kapacitor": "bin/kapacitor.js"
|
|
8
8
|
},
|
|
9
9
|
"optionalDependencies": {
|
|
10
|
-
"@kurrent/kapacitor-darwin-arm64": "0.
|
|
11
|
-
"@kurrent/kapacitor-linux-x64": "0.
|
|
12
|
-
"@kurrent/kapacitor-linux-arm64": "0.
|
|
13
|
-
"@kurrent/kapacitor-linux-musl-x64": "0.
|
|
14
|
-
"@kurrent/kapacitor-linux-musl-arm64": "0.
|
|
15
|
-
"@kurrent/kapacitor-win-x64": "0.
|
|
10
|
+
"@kurrent/kapacitor-darwin-arm64": "0.5.0",
|
|
11
|
+
"@kurrent/kapacitor-linux-x64": "0.5.0",
|
|
12
|
+
"@kurrent/kapacitor-linux-arm64": "0.5.0",
|
|
13
|
+
"@kurrent/kapacitor-linux-musl-x64": "0.5.0",
|
|
14
|
+
"@kurrent/kapacitor-linux-musl-arm64": "0.5.0",
|
|
15
|
+
"@kurrent/kapacitor-win-x64": "0.5.0"
|
|
16
16
|
},
|
|
17
17
|
"files": [
|
|
18
18
|
"bin/",
|