ckforensics 0.2.2 โ 0.2.4
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 +182 -76
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,25 +1,93 @@
|
|
|
1
1
|
# ckforensics
|
|
2
2
|
|
|
3
|
-
**Forensic CLI for Claude Code sessions โ
|
|
3
|
+
> ๐ **Forensic CLI for Claude Code sessions** โ see where your tokens went, what Claude touched, and which skills you missed.
|
|
4
4
|
|
|
5
5
|
[](https://github.com/phong28zk/ckforensics/actions/workflows/ci.yml)
|
|
6
6
|
[](https://www.npmjs.com/package/ckforensics)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://bun.sh)
|
|
9
|
+
[](#claudekit-integration)
|
|
10
|
+
|
|
11
|
+
**One install. Two interfaces.** Standalone CLI **and** ClaudeKit `/ck:forensics` skill โ bundled together.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm i -g ckforensics
|
|
15
|
+
```
|
|
9
16
|
|
|
10
17
|
---
|
|
11
18
|
|
|
12
|
-
##
|
|
19
|
+
## What does it do?
|
|
13
20
|
|
|
14
|
-
|
|
15
|
-
- Claude Code transcripts stored as raw JSONL โ no way to summarize or audit them
|
|
16
|
-
- Sensitive keys / tokens leak into `.jsonl` files that get committed or shared
|
|
17
|
-
- No visibility into token usage, tool calls, or subagent orchestration patterns
|
|
21
|
+
After Claude Code finishes a session, ckforensics parses `~/.claude/projects/**/*.jsonl` and tells you:
|
|
18
22
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
+
```
|
|
24
|
+
โญโ ckforensics summary --days 7 โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
|
|
25
|
+
โ Sessions 19 โ
|
|
26
|
+
โ Input tokens 69,190 โ
|
|
27
|
+
โ Output tokens 3,088,275 โ
|
|
28
|
+
โ Cache read 934,429,934 โ
|
|
29
|
+
โ Total tokens 967,848,242 โ
|
|
30
|
+
โ Estimated cost* $733.8981 โ value extracted from $100 Max โ
|
|
31
|
+
โ Files touched 149 โ
|
|
32
|
+
โ Edit operations 488 โ
|
|
33
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
โญโ ckforensics map --last (where do my tokens go?) โโโโโโโโโโโโโโโฎ
|
|
38
|
+
โ tool:Bash โโโโโโโโ 40.5% 30,444 tok (293 calls) โ
|
|
39
|
+
โ tool:Edit โโโ 16.1% 12,396 tok (98) โ
|
|
40
|
+
โ assistant โโ 11.9% 9,197 tok (563) โ
|
|
41
|
+
โ tool:Read โโ 10.8% 8,327 tok (70) โ
|
|
42
|
+
โ tool:Write โโ 9.3% 7,179 tok (42) โ
|
|
43
|
+
โ โ
|
|
44
|
+
โ Total: 77,204 tokens (ยฑ20% attribution margin) โ
|
|
45
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
โญโ ckforensics suggest --last (what skills would have helped?) โโโฎ
|
|
50
|
+
โ #1 /ck:scout confidence: 85% โ
|
|
51
|
+
โ You ran 23ร Read on src/audit/* in turns 47-89 โ
|
|
52
|
+
โ /ck:scout fans out file discovery in parallel โ
|
|
53
|
+
โ Est. savings: 12k tokens ($0.14) โ
|
|
54
|
+
โ โ
|
|
55
|
+
โ #2 /ck:test confidence: 72% โ
|
|
56
|
+
โ 8ร `bun test` Bash calls in retry loop โ
|
|
57
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
โญโ ckforensics audit --last (session change manifest) โโโโโโโโโโโฎ
|
|
62
|
+
โ ## Subagent Cost Breakdown โ
|
|
63
|
+
โ โ
|
|
64
|
+
โ โ Subagent โ Tokens โ Cost โ Tool calls โ Duration โโ
|
|
65
|
+
โ โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโผโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโคโ
|
|
66
|
+
โ โ Agent: P11 log infraโ 28.9M โ $28.42 โ 20 โ open โโ
|
|
67
|
+
โ โ โโโ nested forensicsโ 28.2M โ $27.91 โ 19 โ open โโ
|
|
68
|
+
โ โ Agent: P06 build โ 646k โ $0.61 โ 2 โ 3h0m โโ
|
|
69
|
+
โ โ Agent: P07 ctx map โ 751k โ $0.47 โ 1 โ 12m28s โโ
|
|
70
|
+
โ โโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโ
|
|
71
|
+
โ โ
|
|
72
|
+
โ โ Identifies runaway subagents in long sessions โ
|
|
73
|
+
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
\* API-rate equivalent (Anthropic Nov 2025 pricing). Subscription users (Pro/Max/Team) pay flat fee โ treat as "value extracted from your plan", not actual billing.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Why does this exist?
|
|
81
|
+
|
|
82
|
+
| Pain | ckforensics |
|
|
83
|
+
|------|-------------|
|
|
84
|
+
| Claude Code stores transcripts as opaque JSONL | Parses into queryable SQLite |
|
|
85
|
+
| You can't see what subagents cost vs the parent | Recursive cost tree per Agent()/Task() |
|
|
86
|
+
| You don't know which skills you skipped using | Pattern detection โ ranked recommendations |
|
|
87
|
+
| Auto-compact is opaque, drops context invisibly | `map` shows what eats your window |
|
|
88
|
+
| Sensitive keys leak into committed jsonl logs | 9 built-in redaction rules |
|
|
89
|
+
| "How much did Claude cost me this week?" | `summary` gives token + USD totals |
|
|
90
|
+
| "What did Claude actually change in that 14h session?" | `audit` produces signed-off manifest |
|
|
23
91
|
|
|
24
92
|
---
|
|
25
93
|
|
|
@@ -29,7 +97,15 @@
|
|
|
29
97
|
npm i -g ckforensics
|
|
30
98
|
```
|
|
31
99
|
|
|
32
|
-
|
|
100
|
+
Single command installs:
|
|
101
|
+
1. **Cross-platform binary** (Linux x64/arm64, macOS Apple Silicon, Windows x64) via npm postinstall download
|
|
102
|
+
2. **ClaudeKit skill** at `~/.claude/skills/ckforensics/` โ auto-activates in next Claude Code session
|
|
103
|
+
|
|
104
|
+
> **Intel Mac:** build from source โ `bun build --compile --target=bun-darwin-x64 src/cli/index.ts --outfile ckforensics`
|
|
105
|
+
>
|
|
106
|
+
> **Opt out of skill copy:** `CKFORENSICS_SKIP_SKILL_INSTALL=1 npm i -g ckforensics`
|
|
107
|
+
|
|
108
|
+
Or grab a binary directly:
|
|
33
109
|
|
|
34
110
|
```bash
|
|
35
111
|
# Linux x64
|
|
@@ -37,116 +113,146 @@ curl -L https://github.com/phong28zk/ckforensics/releases/latest/download/ckfore
|
|
|
37
113
|
-o /usr/local/bin/ckforensics && chmod +x /usr/local/bin/ckforensics
|
|
38
114
|
```
|
|
39
115
|
|
|
40
|
-
Platforms: `linux-x64`, `linux-arm64`, `macos-arm64` (Apple Silicon), `windows-x64`
|
|
41
|
-
|
|
42
|
-
> Intel Mac users: build from source โ `bun build --compile --target=bun-darwin-x64 src/cli/index.ts --outfile ckforensics`
|
|
43
|
-
|
|
44
116
|
---
|
|
45
117
|
|
|
46
118
|
## Quick Start
|
|
47
119
|
|
|
48
120
|
```bash
|
|
49
|
-
#
|
|
50
|
-
ckforensics
|
|
121
|
+
ckforensics ingest # populate DB (~20s for 1000+ jsonl)
|
|
122
|
+
ckforensics summary # weekly totals
|
|
123
|
+
ckforensics audit --last # last session manifest
|
|
124
|
+
ckforensics map --last --top 10 # context heatmap
|
|
125
|
+
ckforensics suggest --last # skill recommendations
|
|
126
|
+
ckforensics doctor # health check
|
|
127
|
+
```
|
|
51
128
|
|
|
52
|
-
|
|
53
|
-
ckforensics summary
|
|
54
|
-
ckforensics summary --days 1 # today
|
|
55
|
-
ckforensics summary --days 30 # month
|
|
129
|
+
**Recommended cron** (hourly auto-ingest):
|
|
56
130
|
|
|
57
|
-
|
|
58
|
-
ckforensics
|
|
131
|
+
```bash
|
|
132
|
+
(crontab -l 2>/dev/null; echo "0 * * * * $(which ckforensics) ingest >> ~/.local/state/ckforensics/logs/ingest.log 2>&1") | crontab -
|
|
133
|
+
```
|
|
59
134
|
|
|
60
|
-
|
|
61
|
-
ckforensics audit --last
|
|
62
|
-
ckforensics audit <session-id> --out review.md
|
|
135
|
+
---
|
|
63
136
|
|
|
64
|
-
|
|
65
|
-
ckforensics redact review.md --in-place
|
|
137
|
+
## ClaudeKit integration
|
|
66
138
|
|
|
67
|
-
|
|
68
|
-
ckforensics export summary --format json | jq
|
|
69
|
-
ckforensics export sessions --format csv --out sessions.csv
|
|
139
|
+
When installed, `/ck:forensics` is available inside Claude Code:
|
|
70
140
|
|
|
71
|
-
|
|
72
|
-
|
|
141
|
+
```
|
|
142
|
+
You: "show me last session cost"
|
|
143
|
+
Claude: [auto-invokes /ck:forensics โ reads SKILL.md โ runs ckforensics audit --last]
|
|
144
|
+
Claude: "Last session was 18h, $1102 API-equivalent. Top files: ..."
|
|
73
145
|
```
|
|
74
146
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
147
|
+
**Triggers** (skill description picks these up):
|
|
148
|
+
- "what did Claude touch this session"
|
|
149
|
+
- "show me last session cost"
|
|
150
|
+
- "where did my tokens go"
|
|
151
|
+
- "audit last session"
|
|
152
|
+
- "what skill should I have used"
|
|
153
|
+
- `/ck:forensics summary` / `/ck:forensics audit` / etc
|
|
81
154
|
|
|
82
|
-
|
|
155
|
+
The skill ships with 3 workflows:
|
|
156
|
+
- **`workflow-eod.md`** โ end-of-day session review
|
|
157
|
+
- **`workflow-pre-commit.md`** โ generate commit message + redact before commit
|
|
158
|
+
- **`workflow-weekly-retro.md`** โ Sunday retrospective
|
|
83
159
|
|
|
84
|
-
|
|
160
|
+
---
|
|
85
161
|
|
|
86
|
-
|
|
87
|
-
- **Subscription users (Pro / Max / Team):** flat plan fee covers this; treat the number as **"value extracted"** from your subscription
|
|
162
|
+
## Storage
|
|
88
163
|
|
|
89
|
-
|
|
164
|
+
DB at XDG-compliant path (mode `0600`):
|
|
90
165
|
|
|
91
|
-
|
|
166
|
+
| OS | Path |
|
|
167
|
+
|----|------|
|
|
168
|
+
| Linux | `~/.local/share/ckforensics/store.db` |
|
|
169
|
+
| macOS | `~/Library/Application Support/ckforensics/store.db` |
|
|
170
|
+
| Windows | `%APPDATA%\ckforensics\store.db` |
|
|
92
171
|
|
|
93
|
-
|
|
172
|
+
Logs (daily-rotated):
|
|
94
173
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
174
|
+
| OS | Path |
|
|
175
|
+
|----|------|
|
|
176
|
+
| Linux | `~/.local/state/ckforensics/logs/` |
|
|
177
|
+
| macOS | `~/Library/Logs/ckforensics/` |
|
|
178
|
+
| Windows | `%LOCALAPPDATA%\ckforensics\Logs\` |
|
|
179
|
+
|
|
180
|
+
**Nothing leaves your machine.** No telemetry. No cloud sync. Run `ckforensics path` to see resolved paths.
|
|
98
181
|
|
|
99
182
|
---
|
|
100
183
|
|
|
101
184
|
## Feature Matrix
|
|
102
185
|
|
|
103
|
-
| Feature | ckforensics | ccusage | Native CC |
|
|
104
|
-
|
|
186
|
+
| Feature | ckforensics | ccusage | Native CC `/usage` |
|
|
187
|
+
|---------|:-----------:|:-------:|:--------------------:|
|
|
105
188
|
| Local SQLite storage | โ
| โ
| โ |
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
189
|
+
| Token usage analytics | โ
| โ
| โ
(live only) |
|
|
190
|
+
| Version-aware cost pricing | โ
| ๐ก | โ
|
|
|
191
|
+
| Subagent cost forensics (recursive) | โ
| โ | โ |
|
|
192
|
+
| Context window heatmap | โ
| โ | โ |
|
|
193
|
+
| Pre-compact simulation | โ
| โ | โ |
|
|
194
|
+
| Skill recommendation engine | โ
| โ | โ |
|
|
109
195
|
| Session change manifest (diff + reasoning) | โ
| โ | โ |
|
|
110
|
-
|
|
|
111
|
-
| Markdown / JSON / CSV export | โ
|
|
|
112
|
-
| Offline
|
|
196
|
+
| Secret redaction (9 rules) | โ
| โ | โ |
|
|
197
|
+
| Markdown / JSON / CSV export | โ
| ๐ก | โ |
|
|
198
|
+
| Offline, zero telemetry | โ
| โ
| โ
|
|
|
113
199
|
| Cross-platform binaries | โ
| โ | โ
|
|
|
200
|
+
| ClaudeKit skill bundled | โ
| โ | โ |
|
|
114
201
|
|
|
115
202
|
---
|
|
116
203
|
|
|
117
204
|
## Commands
|
|
118
205
|
|
|
119
|
-
| Command |
|
|
120
|
-
|
|
121
|
-
| `ingest` | Parse JSONL
|
|
122
|
-
| `summary` | Token + cost
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
206
|
+
| Command | Purpose |
|
|
207
|
+
|---------|---------|
|
|
208
|
+
| `ingest` | Parse JSONL โ SQLite (idempotent + incremental, optional `--watch`) |
|
|
209
|
+
| `summary` | Token + cost rollup over rolling window (default 7d) |
|
|
210
|
+
| `sessions` | List sessions with cost, duration, model |
|
|
211
|
+
| `audit` | Per-session manifest: diffs + reasoning + subagent breakdown |
|
|
212
|
+
| `map` | Context-window heatmap by category, snapshot/diff/pin |
|
|
213
|
+
| `suggest` | Skill recommendations from detected tool patterns |
|
|
214
|
+
| `skills` | Browse ClaudeKit skill catalog with usage stats |
|
|
215
|
+
| `export` | Pipe-friendly export (markdown, JSON, CSV) |
|
|
216
|
+
| `redact` | Strip 9 secret patterns from a file |
|
|
217
|
+
| `doctor` | Health check (DB, paths, schema version, log activity) |
|
|
218
|
+
| `path` | Show all resolved file system paths |
|
|
219
|
+
|
|
220
|
+
Run `ckforensics <cmd> --help` for flags.
|
|
129
221
|
|
|
130
222
|
---
|
|
131
223
|
|
|
132
|
-
##
|
|
133
|
-
|
|
134
|
-
See [docs/architecture.md](docs/architecture.md) โ module overview and data-flow diagram.
|
|
224
|
+
## About cost numbers
|
|
135
225
|
|
|
136
|
-
|
|
226
|
+
Cost is **API-rate equivalent** computed from token counts ร Anthropic's published prices ([Nov 2025 snapshot](https://platform.claude.com/docs/en/about-claude/pricing)).
|
|
137
227
|
|
|
138
|
-
|
|
228
|
+
- **API users:** approximates your actual bill (ยฑ10-30% for cache-pricing edge cases)
|
|
229
|
+
- **Subscription users (Pro / Max / Team):** flat plan fee covers this โ treat the number as **"value extracted"** from your subscription
|
|
139
230
|
|
|
140
|
-
|
|
231
|
+
Example: a 14h Opus 4.7 session showing `$166` means you'd pay ~$166 at API rates โ your $100/mo Max plan covers it with positive ROI.
|
|
141
232
|
|
|
142
|
-
|
|
233
|
+
---
|
|
143
234
|
|
|
144
|
-
##
|
|
235
|
+
## Documentation
|
|
145
236
|
|
|
146
|
-
|
|
237
|
+
| Doc | Topic |
|
|
238
|
+
|-----|-------|
|
|
239
|
+
| [docs/architecture.md](docs/architecture.md) | Module overview, data flow |
|
|
240
|
+
| [docs/threat-model.md](docs/threat-model.md) | Privacy stance, redaction guarantees |
|
|
241
|
+
| [docs/jsonl-schema-v1.md](docs/jsonl-schema-v1.md) | Reverse-engineered JSONL event types |
|
|
242
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, PR checklist, fixture rules |
|
|
243
|
+
| [ROADMAP.md](ROADMAP.md) | v0.1.x โ v0.6+ feature plans |
|
|
244
|
+
| [CHANGELOG.md](CHANGELOG.md) | Version history |
|
|
147
245
|
|
|
148
246
|
---
|
|
149
247
|
|
|
150
248
|
## License
|
|
151
249
|
|
|
152
250
|
MIT โ [LICENSE](LICENSE) โ Copyright (c) 2026 phong28zk
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## Acknowledgements
|
|
255
|
+
|
|
256
|
+
- [ClaudeKit](https://github.com/phong28zk) ecosystem for the `/ck:*` skill pattern
|
|
257
|
+
- [Anthropic](https://anthropic.com) for Claude Code + the public JSONL transcript format
|
|
258
|
+
- [Bun](https://bun.sh) for single-binary compilation that makes cross-platform distribution painless
|