ckforensics 0.2.1 → 0.2.3

package/.claude/skills/ckforensics/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: ck:forensics
+description: "Forensic analysis of Claude Code sessions — token cost, context map, audit manifest, skill recommendations. Use when user asks 'what did Claude touch', 'where did my tokens go', 'how much did this session cost', 'show last session', 'what skill should I have used', or wants post-hoc review of CC work."
+category: dev-tools
+keywords: [claude-code, audit, forensics, observability, token-cost, context, skill-recommender, session-review]
+argument-hint: "summary|sessions|audit|map|suggest|skills|ingest [args]"
+metadata:
+  author: phong28zk
+  version: "0.2.1"
+  upstream: "https://github.com/phong28zk/ckforensics"
+---
+
+# ck:forensics — Claude Code Session Forensics
+
+Read-only post-hoc analysis of `~/.claude/projects/**/*.jsonl` transcripts. Surfaces:
+- **What was burned:** tokens, $, time, by tool/skill/file
+- **What changed:** files touched, diff, reasoning trail, subagent attribution
+- **What lives in context:** heatmap of items by category (tool_result, message, ...)
+- **What you missed:** skills that would have replaced repeated manual sequences
+
+Powered by the `ckforensics` CLI (npm `ckforensics@^0.2.1`). Local-only, no telemetry.
+
+---
+
+## Default (No Arguments)
+
+If invoked without arguments, use `AskUserQuestion` to present operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `summary` | Token + cost rollup (last 7d default) |
+| `sessions` | List recent sessions with cost/duration |
+| `audit` | Per-session change manifest (files, diff, reasoning) |
+| `map` | Context-window heatmap (what eats tokens?) |
+| `suggest` | Skills that would have helped (pattern detection) |
+| `skills` | List/search indexed skills with usage stats |
+| `ingest` | Refresh DB from `~/.claude/projects/` |
+
+Present via `AskUserQuestion` with header "Forensics" and question "Which analysis?".
+
+---
+
+## Installation Check
+
+Before running any command, ensure CLI is installed:
+
+```bash
+command -v ckforensics >/dev/null || {
+  echo "ckforensics not installed. Install with: npm i -g ckforensics"
+  exit 1
+}
+```
+
+If missing, ask user to install before proceeding.
+
+---
+
+## Workflows
+
+| Workflow | Reference |
+|----------|-----------|
+| End-of-day session review | `references/workflow-eod.md` |
+| Pre-commit audit | `references/workflow-pre-commit.md` |
+| Weekly cost retro | `references/workflow-weekly-retro.md` |
+| Command reference | `references/commands.md` |
+| Output interpretation | `references/interpretation.md` |
+
+---
+
+## Core Commands
+
+### `summary [--days N]`
+
+Token/cost rollup. Default 7 days.
+
+```bash
+ckforensics summary             # last 7 days
+ckforensics summary --days 1    # today
+ckforensics summary --days 30   # this month
+ckforensics summary --json      # for piping to jq
+```
+
+**Cost interpretation:** API-rate equivalent. Subscription users (Pro/Max) pay flat fee — treat as "value extracted", not actual bill. See `references/interpretation.md`.
+
+### `audit [--last|<session-id>] [--out FILE]`
+
+Per-session change manifest:
+- Header (model, duration, cost, total events)
+- Files changed (with chronological edits + reasoning quotes)
+- Subagent dispatches + recursive cost breakdown
+- Reasoning correlator: each tool call linked to preceding assistant text
+
+```bash
+ckforensics audit --last                            # most recent session
+ckforensics audit <session-id> --out review.md      # for PR review
+ckforensics audit --last --format json | jq         # script-friendly
+```
+
+### `map [--last|<session-id>] [--top N]`
+
+Context-window heatmap. Shows what categories eat the most tokens:
+- `tool:Bash` → shell output
+- `tool:Read` / `tool:Edit` → file ops
+- `assistant` / `user` → messages
+- `unknown` → unattributable
+
+Use `--simulate-compact` to project what survives next auto-compact.
+
+```bash
+ckforensics map --last --top 20
+ckforensics map --simulate-compact --target-pct 50
+```
+
+### `suggest [--session ID|--last|--days N] [--min-confidence 70]`
+
+Skill recommendations: detects repeated tool patterns and matches against `~/.claude/skills/` catalog. Suggests skills that would have replaced manual work.
+
+```bash
+ckforensics suggest --last                       # for most recent session
+ckforensics suggest --days 7 --min-confidence 30  # weekly retro
+```
+
+### `sessions [--project SLUG] [--limit N]`
+
+List recent sessions with cost/duration. Filter by project.
+
+```bash
+ckforensics sessions --limit 10
+ckforensics sessions --project ckforensics --limit 50
+```
+
+### `skills [--unused|--used] [--search QUERY] [--refresh]`
+
+List indexed skills. `--unused` shows skills you have but never invoked. Discoverability tool.
+
+```bash
+ckforensics skills --refresh        # re-scan ~/.claude/skills/
+ckforensics skills --unused | head  # what am I missing?
+```
+
+### `ingest`
+
+Refresh DB from `~/.claude/projects/`. Incremental — only new jsonl content.
+
+```bash
+ckforensics ingest                  # one-shot
+ckforensics ingest --watch          # poll every 5s
+```
+
+---
+
+## When to Use This Skill
+
+**After CC session:** Run `audit --last` to review what Claude changed.
+
+**Cost review:** Run `summary` to see token burn vs subscription value.
+
+**Habit improvement:** Run `suggest --days 7` weekly to find skill opportunities.
+
+**Context optimization:** Run `map --last` when session hits compaction wall — see what eats tokens.
+
+**Pre-commit:** Run `audit --last --out review.md` then `redact review.md --in-place` before sharing.
+
+---
+
+## Output Interpretation
+
+| Pattern | Meaning |
+|---------|---------|
+| `tool:Bash` >40% of map | Heavy shell output; consider piping to `tail`/`head` |
+| `tool:Read` repeats on same dir | `/ck:scout` candidate |
+| Subagent cost > main cost | Runaway subagent — review prompt scope |
+| Cost in red (>$10) | High-value session; worth saving manifest for retro |
+| Suggest confidence <50% | Probably noise; only act on ≥70% |
+
+See `references/interpretation.md` for full guide.
+
+---
+
+## Important Notes
+
+- **All operations are read-only.** Never modifies `~/.claude/projects/`.
+- **Cost is API-rate estimate** (Nov 2025 Anthropic pricing); subscription users see flat fee.
+- **±20% attribution margin** on context map (heuristic-based).
+- **Cache local at** `~/.local/share/ckforensics/store.db` (mode 0600).
+- **Logs at** `~/.local/state/ckforensics/logs/` (Linux), `~/Library/Logs/ckforensics/` (macOS).
+
+## Token Efficiency
+
+- Activate `ck:context-engineering` skill if running `audit` or `map` on very long sessions (output can be 100k+ tokens of markdown — pipe to file).
+- Use `--json` for downstream tools; avoids markdown formatting overhead.
+- For routine ingest, cron handles it: `0 * * * * ckforensics ingest >> ~/.local/state/ckforensics/logs/ingest.log 2>&1`.
+
+**Sacrifice grammar for concision when reporting findings to user.**
+
+---
+
+## Quick Start (User's First Run)
+
+```bash
+npm i -g ckforensics                    # install
+ckforensics doctor                      # verify
+ckforensics ingest                      # populate DB (~20s for 1000+ jsonl)
+ckforensics summary                     # see weekly totals
+ckforensics audit --last | head -50     # review last session
+```

package/.claude/skills/ckforensics/references/commands.md

@@ -0,0 +1,108 @@
+# ck:forensics — Command Reference
+
+Quick reference for every `ckforensics` subcommand exposed via `/ck:forensics`.
+
+## Global flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--db <path>` | XDG data dir | Override SQLite path |
+| `--no-color` | off | Disable ANSI |
+| `-v, --verbose` | off | Info-level logging to stderr |
+| `--debug` | off | Debug-level logging |
+| `--log-dir <path>` | XDG state dir | Override log dir |
+| `--json` | off | Force JSON output globally |
+
+## Subcommands
+
+### `summary [--days N] [--format text|md|json]`
+
+Aggregate token/cost/files across a rolling window.
+
+**Output fields:**
+- `sessionCount`
+- `totalInputTokens`, `totalOutputTokens`, `totalCacheRead`, `totalCacheCreate`
+- `estimatedCostUsd` (API-rate equivalent)
+- `filesTouched`, `editOps`
+- `oldestSession`, `newestSession`
+
+### `sessions [--project SLUG] [--limit N] [--format text|md|csv|json]`
+
+List recent sessions ordered by `started_at DESC`.
+
+**Columns:** ID, Project, Started, Model, Events, Cost, Duration
+
+Cost color-coded: red >$10, yellow $1-10, green <$1, dim — for null.
+
+### `audit [<session-id>|--last] [--out FILE] [--format md|json]`
+
+Per-session change manifest.
+
+**Sections:**
+1. Header (session ID, project, model, duration, cost, total events)
+2. Summary (files changed, lines +/-, edit ops, tokens, cache read)
+3. File Changes (chronological edits, reasoning quotes, unified diff)
+4. Subagent Dispatches (each Agent() / Task() with input + duration)
+5. Subagent Cost Breakdown (nested table with tokens + cost per agent)
+
+Exit codes: 0 success, 3 session not found.
+
+### `map [<session-id>|--last] [--top N=20] [--simulate-compact] [--target-pct N=50]`
+
+Context window heatmap by category.
+
+**Categories:** `tool:<Name>`, `assistant`, `user`, `system_prompt`, `memory`, `skill_load`, `unknown`
+
+Each row: ASCII bar + percentage + token count + item count.
+
+**`--simulate-compact`:** projects which items survive next auto-compact based on documented heuristic.
+
+**Sub-commands:**
+- `ckforensics map --save NAME` — persist snapshot
+- `ckforensics map list` — list saved snapshots
+- `ckforensics map diff <A> <B>` — token movement between snapshots
+- `ckforensics map --pin ITEM_ID --emit-manifest [FILE]` — pinned items → paste-ready markdown
+
+### `suggest [<session-id>|--last|--days N=7] [--min-confidence N=70] [--top N=3] [--format text|md|json]`
+
+Detect repeated tool patterns and recommend skills.
+
+**Patterns detected:**
+- `read-fanout`: ≥5 Reads within 3 adjacent turns on same dir
+- `test-loop`: ≥3 Bash test runs
+- `manual-diff-cycle`: read→edit→read ≥2 cycles
+- `grep-walk`: ≥4 Grep+Read pairs
+- `subagent-skip`: ≥20 main-thread tool calls, no Agent/Task
+
+**Output per rec:** invocation hint (`/ck:scout`), confidence %, est savings (tokens + USD), evidence turns.
+
+### `skills [--unused|--used] [--search QUERY] [--refresh] [--format text|md|csv|json]`
+
+List indexed skills from `~/.claude/skills/`.
+
+- `--refresh` — re-scan SKILL.md frontmatter
+- `--unused` — show skills you've never invoked
+- `--used` — show skills you've activated, with usage count
+- `--search "pattern"` — keyword search
+
+### `ingest [--watch]`
+
+Parse `~/.claude/projects/**/*.jsonl` → SQLite. Idempotent + incremental.
+
+- `--watch` polls every 5s (for cron alternative)
+
+### `redact <file> [--in-place] [--force]`
+
+Apply 9 redaction rules (sk-ant, GH tokens, AWS, JWT, etc.) to a markdown/text file. Use before sharing audit exports.
+
+### `export <view> --format md|json|csv [--out FILE]`
+
+Pipe-friendly export: `summary`, `sessions`, `audit`.
+
+### `doctor`
+
+Health check: DB exists + version, JSONL dir readable, last ingest mtime, log dir writeable, Bun version.
+
+### `path`
+
+Print resolved paths (DB, data dir, JSONL source, log dir, config dir).

package/.claude/skills/ckforensics/references/interpretation.md

@@ -0,0 +1,81 @@
+# ck:forensics — Output Interpretation Guide
+
+How to read what ckforensics tells you, and when to act on it.
+
+## Cost interpretation
+
+| Display | Meaning |
+|---------|---------|
+| `$X.XX` (green) | <$1 — typical small session |
+| `$X.XX` (yellow) | $1-10 — substantive work |
+| `$X.XX` (red) | >$10 — high-value session, worth saving manifest |
+| `unknown` / `—` | Cost not estimable (missing model in DB, pre-pricing-fix) |
+| `*` footnote | API-rate equivalent, not actual subscription bill |
+
+**Two cost numbers compared:**
+- ckforensics `Estimated Cost`: token count × Anthropic published rates
+- CC live statusline: real-time `cost.total_cost_usd` from CC's internal calc
+
+Discrepancy expected (CC may exclude some cache pricing). Within 30% = normal.
+
+**For subscription users:** the cost number = "value extracted from your $X/mo plan", not a bill.
+
+## Map heatmap thresholds
+
+| Pattern | Diagnostic | Action |
+|---------|-----------|--------|
+| `tool:Bash` >40% | Heavy shell output | Pipe to `head`/`tail`, redirect logs, or limit verbose flags |
+| `tool:Read` >30% | Excessive file reads | Use `/ck:scout` for batched discovery |
+| `tool:Edit` >30% | Lots of edits | Normal for code-heavy session; check for thrashing |
+| `assistant` >40% | Very long replies | Verbose mode, summarisation overhead |
+| `unknown` >10% | Attribution failure | Schema drift; report to ckforensics issues |
+
+## Suggest confidence brackets
+
+| Confidence | Meaning | Action |
+|------------|---------|--------|
+| 80-100% | Strong signal, multi-pattern match | Try the skill next session |
+| 60-80% | Plausible, single pattern | Worth reading description |
+| 40-60% | Weak — likely keyword coincidence | Skip unless desperate |
+| <40% | Noise | Ignore |
+
+Default threshold = 70. Lower with `--min-confidence 30` if seeing no recs.
+
+## Audit manifest sections
+
+### Files changed
+
+Each file shows chronological edits with reasoning quote. **Read the reasoning** — it's the assistant's intent text before the tool call, not post-hoc explanation. Useful for:
+- Understanding *why* an edit was made
+- Catching scope creep (intent vs action mismatch)
+- Composing PR descriptions (reasoning often is the PR body)
+
+### Subagent Cost Breakdown
+
+Nested table. Top-level rows = direct Agent()/Task() calls from main thread. Indented rows = nested (subagent inside subagent).
+
+**Red flags:**
+- Single subagent with >$5 cost in <10 tool calls = runaway
+- "open" duration → subagent still running (session paused?)
+- Many small subagents (≤2 calls each) = excessive fanout
+
+### Reasoning correlator
+
+Each tool call gets a "Reasoning:" quote. If reasoning is empty/unhelpful:
+- Assistant didn't narrate (rare)
+- Tool fired in middle of multi-block message (correlator picks last text block)
+- Subagent invocation (reasoning belongs to parent dispatch)
+
+## Sessions list signals
+
+- Same project, multiple short sessions same day → context flushing too often
+- Single 10+ hour session → consider checkpointing via context map
+- Cost trending up week-over-week → instrument with `summary --days N`
+
+## When ingest finds nothing
+
+If `ckforensics ingest` reports 0 new events:
+1. Check `ckforensics doctor` — last ingest mtime
+2. Verify `~/.claude/projects/` has recent jsonl: `ls -lt ~/.claude/projects/*/*.jsonl | head`
+3. CC may be on different config dir (CLAUDE_CONFIG_DIR env var) — set `--db` accordingly
+4. Force re-ingest from scratch: `rm ~/.local/share/ckforensics/store.db && ckforensics ingest`

package/.claude/skills/ckforensics/references/workflow-eod.md

@@ -0,0 +1,56 @@
+# End-of-Day Session Review Workflow
+
+Pattern: after a substantial Claude Code session, run forensics to know what shipped, what burned, what to remember.
+
+## Flow
+
+```
+1. ckforensics ingest                       # refresh DB
+2. ckforensics summary --days 1             # today's totals
+3. ckforensics audit --last --out eod.md    # capture manifest
+4. ckforensics suggest --last               # skills that would have helped
+5. ckforensics map --last --top 15          # what ate the context
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "wrap up this session"
+- "what did I do today"
+- "end of day review"
+- "summary of last session"
+- "did Claude do anything weird"
+
+## What Claude should do
+
+1. Run the 5 commands above (or relevant subset).
+2. **Summarise**, don't paste raw output to user. Surface:
+   - Total cost (API-rate) + duration
+   - Top 3 files changed (by lines or by importance from reasoning quotes)
+   - Any subagent that cost >$1 (flag for review)
+   - Top 1-2 skill recommendations with confidence ≥70
+   - Context map insight: what ate most tokens
+3. **Offer next actions:**
+   - "Save audit manifest as PR description?" → use `eod.md`
+   - "Dismiss low-value skill recs?" → `~/.config/ckforensics/dismissed.json`
+   - "Schedule cron for daily ingest?" → crontab snippet
+
+## Example response template
+
+```
+Today's session burned $X.XX over Y hours. Modified Z files (top: A, B, C).
+
+Notable:
+- Subagent "P11 log infra" cost $28 — runaway, worth reviewing
+- Skill /ck:scout would have replaced 23× Read on src/audit/* (saves ~12k tokens)
+- Context map: tool:Bash 40%, tool:Edit 16% — heavy shell + editing
+
+Manifest saved to eod.md. Want me to draft a commit message from it?
+```
+
+## Anti-patterns
+
+- ❌ Paste full audit markdown (1000+ lines) to user
+- ❌ Run all 5 commands when user only asked "cost today"
+- ❌ Recommend skills with confidence <70 without flagging confidence
+- ❌ Skip subagent cost breakdown — that's the highest-signal section

package/.claude/skills/ckforensics/references/workflow-pre-commit.md

@@ -0,0 +1,63 @@
+# Pre-Commit Audit Workflow
+
+Pattern: before user runs `git commit`, generate a manifest of what Claude touched and use it as commit/PR body draft.
+
+## Flow
+
+```
+1. ckforensics ingest                       # ensure DB current
+2. ckforensics audit --last --out review.md # capture this session's manifest
+3. ckforensics redact review.md --in-place  # strip secrets before sharing
+4. (user opens review.md, copies relevant sections to commit body)
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "ready to commit"
+- "draft a commit message from this session"
+- "what should the PR description say"
+- "review what I just did before committing"
+
+## What Claude should do
+
+1. Run `audit --last` to get the manifest.
+2. Pipe through `redact` (always, never skip — secrets risk).
+3. Extract from manifest:
+   - **Files changed** + line counts (for `git diff --stat` equivalent)
+   - **Reasoning quotes** per file (often makes the PR body)
+   - **Subagent contributions** (mention if subagents did significant work)
+4. **Draft conventional commit**:
+   ```
+   <type>(<scope>): <subject>
+   
+   <body — TLDR of what changed and why, from reasoning>
+   
+   <body — files affected, key decisions>
+   ```
+5. **Surface anything suspicious:**
+   - Files touched in unexpected directories
+   - Reasoning that doesn't match the actions (intent drift)
+   - Subagents with high cost (worth mentioning in PR)
+
+## Integration with ck:git
+
+After draft, hand off to `/ck:git cm` for execution:
+```
+ckforensics audit --last --out review.md
+ckforensics redact review.md --in-place
+# Claude reads review.md, drafts commit message
+# Hand to /ck:git cm — user reviews + executes
+```
+
+Or pipe directly (v0.5 phase 12 will support this):
+```
+ckforensics commit --phase last | ck:git cm --message-stdin
+```
+
+## Anti-patterns
+
+- ❌ Skip redaction — manifests can contain edited file contents = secrets risk
+- ❌ Paste raw manifest as commit body (too long, unstructured)
+- ❌ Auto-commit — always show draft, let user approve via /ck:git
+- ❌ Forget to mention subagents — they did work that deserves credit/audit

package/.claude/skills/ckforensics/references/workflow-weekly-retro.md

@@ -0,0 +1,72 @@
+# Weekly Retro Workflow
+
+Pattern: every Sunday (or Monday morning), look back at the week — cost trends, skill discovery, runaway sessions.
+
+## Flow
+
+```
+1. ckforensics ingest                                 # ensure DB current
+2. ckforensics summary --days 7                       # weekly rollup
+3. ckforensics sessions --limit 20                    # week's sessions
+4. ckforensics suggest --days 7 --min-confidence 50   # patterns to fix
+5. ckforensics skills --unused | head -20             # discovery
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "weekly retro"
+- "what did I spend on Claude Code this week"
+- "any patterns I should fix in my workflow"
+- "show me sessions ranked by cost"
+- "what skills should I learn"
+
+## What Claude should do
+
+1. **Summary numbers first** — cost, session count, vs previous week if possible (`--days 14` then compute delta).
+2. **Top 5 most expensive sessions** with project + duration. Flag anything over $50.
+3. **Recurring patterns** from `suggest --days 7`:
+   - List top 3 skill recommendations
+   - Group by pattern type (e.g. "read-fanout detected 4× this week")
+4. **Skill discovery**:
+   - From `skills --unused`, pick 3-5 that match user's project work (filter by keyword overlap with recent session topics)
+   - Format as "consider trying: /ck:xyz — <description>"
+5. **Anomaly check**:
+   - Any single session >$100? Flag for review.
+   - Any subagent that ran >1h? Worth investigating.
+6. **Optional: write retro to docs/**:
+   - `docs/retros/YYYY-MM-DD-week-N.md`
+   - Auto-fill summary + recommendations sections
+   - User edits notes manually after
+
+## Example response template
+
+```
+Weekly retro (Mon 2026-05-04 → Sun 2026-05-10):
+
+📊 Totals: $733 API-equivalent across 19 sessions, 967M tokens
+   vs prev week: +180% (last week $260 / 12 sessions)
+   
+🔥 Top sessions:
+   1. project-noname  18h56m  $1102  (Tue, 4082 events)
+   2. MQL5            2h21m   $29    (Tue)
+   3. career-launchpad 19h    $32    (Wed)
+
+📚 Skill recommendations:
+   - /ck:scout (4× read-fanout patterns this week — 50k tok save)
+   - /ck:test (3× test-loop patterns — 15k tok save)
+
+💡 Try these unused skills:
+   - /ck:retro — auto-generate this report (would replace this manual flow)
+   - /ck:journal — capture session reflections automatically
+   - /ck:debug — systematic debugging when stuck
+
+⚠️ Notable: session #1 was 18h Opus — consider checkpointing context mid-way.
+```
+
+## Anti-patterns
+
+- ❌ Compare cost to subscription price as if it's the bill — it's API-equivalent, frame as "value extracted"
+- ❌ Recommend ALL unused skills (150+) — filter to relevant per project context
+- ❌ Skip anomaly check — outliers are the highest-signal items
+- ❌ Long bullet lists — keep tight, 3-5 items per category max

package/.claude/skills/ckforensics/scripts/session-overview.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+session-overview.py — One-shot session report for ck:forensics skill.
+
+Runs multiple `ckforensics` CLI commands and stitches a single JSON
+report. Saves Claude from chaining 4-5 Bash calls when answering
+"summarize this session" prompts.
+
+Usage:
+    python3 session-overview.py [--session-id ID] [--days N]
+    python3 session-overview.py --last           # default — most recent session
+
+Output: JSON on stdout with shape:
+    {
+      "schema": "ck-forensics-overview-v1",
+      "generatedAt": "ISO8601",
+      "scope": {"sessionId": "...", "days": 7, "lastOnly": true},
+      "summary":   { ... },     # `ckforensics summary --json` data
+      "session":   { ... },     # one row from `ckforensics sessions --json`
+      "audit":     { ... },     # `ckforensics audit --json` (manifest)
+      "suggest":   [ ... ],     # top recs from `ckforensics suggest --json`
+      "map":       { ... }      # context map heatmap
+    }
+
+Errors are reported as {"schema": "error", "error": "..."} with exit 1.
+
+Stdlib only — no third-party deps required. Compatible with Python 3.8+.
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+
+def check_cli_installed() -> None:
+    """Verify ckforensics CLI is on PATH; exit 1 with clear error if not."""
+    if shutil.which("ckforensics") is None:
+        emit_error(
+            "ckforensics CLI not installed. "
+            "Install with: npm i -g ckforensics"
+        )
+        sys.exit(1)
+
+
+def run_cli(args: list) -> dict:
+    """
+    Run `ckforensics <args>` with --json and return parsed output.
+    Raises CalledProcessError on non-zero exit (caller decides whether to ignore).
+    """
+    cmd = ["ckforensics", *args, "--json"]
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        # Many subcommands exit 3 when no data — return empty rather than fail
+        if result.returncode == 3:
+            return {}
+        raise subprocess.CalledProcessError(
+            result.returncode, cmd, result.stdout, result.stderr
+        )
+    return json.loads(result.stdout) if result.stdout.strip() else {}
+
+
+def emit_error(msg: str) -> None:
+    """Write error envelope to stdout."""
+    print(json.dumps({"schema": "error", "error": msg}), flush=True)
+
+
+def collect_overview(session_id: str | None, days: int, last: bool) -> dict:
+    """Gather all sections; failures in individual sections become null."""
+    overview = {
+        "schema": "ck-forensics-overview-v1",
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+        "scope": {"sessionId": session_id, "days": days, "lastOnly": last},
+        "summary": None,
+        "session": None,
+        "audit": None,
+        "suggest": None,
+        "map": None,
+    }
+
+    # 1. Summary — rolling window
+    try:
+        overview["summary"] = run_cli(["summary", "--days", str(days)]).get("data")
+    except Exception as e:
+        overview["summary"] = {"error": str(e)}
+
+    # 2. Session metadata — pick from list or by id
+    try:
+        sessions_envelope = run_cli(["sessions", "--limit", "1"])
+        sessions = sessions_envelope.get("data", [])
+        if session_id:
+            # Filter to specific session if requested
+            sessions = [s for s in sessions if s.get("id") == session_id]
+        overview["session"] = sessions[0] if sessions else None
+    except Exception as e:
+        overview["session"] = {"error": str(e)}
+
+    # 3. Audit manifest — uses --last unless explicit id given
+    audit_args = ["audit", "--last"] if last or not session_id else ["audit", session_id]
+    try:
+        overview["audit"] = run_cli(audit_args)
+    except Exception as e:
+        overview["audit"] = {"error": str(e)}
+
+    # 4. Suggest — same scope as audit
+    suggest_args = ["suggest", "--last", "--min-confidence", "30", "--top", "3"]
+    if session_id and not last:
+        suggest_args = ["suggest", "--session", session_id, "--min-confidence", "30", "--top", "3"]
+    try:
+        overview["suggest"] = run_cli(suggest_args).get("data", [])
+    except Exception as e:
+        overview["suggest"] = {"error": str(e)}
+
+    # 5. Map — top-10 heatmap categories
+    map_args = ["map", "--last", "--top", "10"]
+    if session_id and not last:
+        map_args = ["map", session_id, "--top", "10"]
+    try:
+        overview["map"] = run_cli(map_args).get("data")
+    except Exception as e:
+        overview["map"] = {"error": str(e)}
+
+    return overview
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="session-overview",
+        description="Unified session report — runs multiple ckforensics commands and merges output.",
+    )
+    p.add_argument("--session-id", help="Explicit session UUID (defaults to --last)")
+    p.add_argument("--days", type=int, default=7, help="Summary window in days (default 7)")
+    p.add_argument(
+        "--last",
+        action="store_true",
+        default=True,
+        help="Use most recent session (default behavior)",
+    )
+    return p.parse_args()
+
+
+def main() -> int:
+    check_cli_installed()
+    args = parse_args()
+    last = args.last and not args.session_id
+
+    try:
+        overview = collect_overview(args.session_id, args.days, last)
+        print(json.dumps(overview, indent=2, default=str))
+        return 0
+    except Exception as e:
+        emit_error(f"unexpected error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/README.md

@@ -1,25 +1,93 @@
 # ckforensics
 
-**Forensic CLI for Claude Code sessions — audit, redact, export your transcripts.**
+> 🔍 **Forensic CLI for Claude Code sessions** — see where your tokens went, what Claude touched, and which skills you missed.
 
 [![CI](https://github.com/phong28zk/ckforensics/actions/workflows/ci.yml/badge.svg)](https://github.com/phong28zk/ckforensics/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ckforensics)](https://www.npmjs.com/package/ckforensics)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Bun](https://img.shields.io/badge/runtime-Bun-f472b6)](https://bun.sh)
+[![ClaudeKit Skill](https://img.shields.io/badge/ClaudeKit-/ck:forensics-9333ea)](#claudekit-integration)
+
+**One install. Two interfaces.** Standalone CLI **and** ClaudeKit `/ck:forensics` skill — bundled together.
+
+```bash
+npm i -g ckforensics
+```
 
 ---
 
-## Why ckforensics
+## What does it do?
 
-**Pain:**
-- Claude Code transcripts stored as raw JSONL — no way to summarize or audit them
-- Sensitive keys / tokens leak into `.jsonl` files that get committed or shared
-- No visibility into token usage, tool calls, or subagent orchestration patterns
+After Claude Code finishes a session, ckforensics parses `~/.claude/projects/**/*.jsonl` and tells you:
 
-**Solution:**
-- Ingest all sessions into a local SQLite DB — queryable, indexed, stays on disk
-- Redact 9 secret patterns (API keys, AWS creds, JWTs, PEM blocks) before any export
-- CLI commands for summary, audit, session diff, and export — no cloud, no telemetry
+```
+╭─ ckforensics summary --days 7 ──────────────────────────────────╮
+│  Sessions          19                                            │
+│  Input tokens      69,190                                        │
+│  Output tokens     3,088,275                                     │
+│  Cache read        934,429,934                                   │
+│  Total tokens      967,848,242                                   │
+│  Estimated cost*   $733.8981  ← value extracted from $100 Max    │
+│  Files touched     149                                           │
+│  Edit operations   488                                           │
+╰──────────────────────────────────────────────────────────────────╯
+```
+
+```
+╭─ ckforensics map --last (where do my tokens go?) ──────────────╮
+│  tool:Bash    ████████  40.5%   30,444 tok  (293 calls)          │
+│  tool:Edit    ███       16.1%   12,396 tok  (98)                 │
+│  assistant    ██        11.9%    9,197 tok  (563)                │
+│  tool:Read    ██        10.8%    8,327 tok  (70)                 │
+│  tool:Write   ██         9.3%    7,179 tok  (42)                 │
+│                                                                   │
+│  Total: 77,204 tokens  (±20% attribution margin)                 │
+╰──────────────────────────────────────────────────────────────────╯
+```
+
+```
+╭─ ckforensics suggest --last (what skills would have helped?) ──╮
+│  #1  /ck:scout                                  confidence: 85% │
+│      You ran 23× Read on src/audit/* in turns 47-89             │
+│      /ck:scout fans out file discovery in parallel              │
+│      Est. savings: 12k tokens ($0.14)                           │
+│                                                                   │
+│  #2  /ck:test                                   confidence: 72% │
+│      8× `bun test` Bash calls in retry loop                     │
+╰──────────────────────────────────────────────────────────────────╯
+```
+
+```
+╭─ ckforensics audit --last  (session change manifest) ──────────╮
+│  ## Subagent Cost Breakdown                                      │
+│                                                                   │
+│  │ Subagent           │ Tokens │ Cost   │ Tool calls │ Duration ││
+│  ├────────────────────┼────────┼────────┼────────────┼──────────┤│
+│  │ Agent: P11 log infra│ 28.9M │ $28.42 │ 20         │ open     ││
+│  │ └── nested forensics│ 28.2M │ $27.91 │ 19         │ open     ││
+│  │ Agent: P06 build    │ 646k  │ $0.61  │ 2          │ 3h0m     ││
+│  │ Agent: P07 ctx map  │ 751k  │ $0.47  │ 1          │ 12m28s   ││
+│  └────────────────────┴────────┴────────┴────────────┴──────────┘│
+│                                                                   │
+│  ↑ Identifies runaway subagents in long sessions                 │
+╰──────────────────────────────────────────────────────────────────╯
+```
+
+\* 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.
+
+---
+
+## Why does this exist?
+
+| Pain | ckforensics |
+|------|-------------|
+| Claude Code stores transcripts as opaque JSONL | Parses into queryable SQLite |
+| You can't see what subagents cost vs the parent | Recursive cost tree per Agent()/Task() |
+| You don't know which skills you skipped using | Pattern detection → ranked recommendations |
+| Auto-compact is opaque, drops context invisibly | `map` shows what eats your window |
+| Sensitive keys leak into committed jsonl logs | 9 built-in redaction rules |
+| "How much did Claude cost me this week?" | `summary` gives token + USD totals |
+| "What did Claude actually change in that 14h session?" | `audit` produces signed-off manifest |
 
 ---
 
@@ -29,7 +97,15 @@
 npm i -g ckforensics
 ```
 
-Or download a prebuilt binary from [Releases](https://github.com/phong28zk/ckforensics/releases):
+Single command installs:
+1. **Cross-platform binary** (Linux x64/arm64, macOS Apple Silicon, Windows x64) via npm postinstall download
+2. **ClaudeKit skill** at `~/.claude/skills/ckforensics/` — auto-activates in next Claude Code session
+
+> **Intel Mac:** build from source — `bun build --compile --target=bun-darwin-x64 src/cli/index.ts --outfile ckforensics`
+>
+> **Opt out of skill copy:** `CKFORENSICS_SKIP_SKILL_INSTALL=1 npm i -g ckforensics`
+
+Or grab a binary directly:
 
 ```bash
 # Linux x64
@@ -37,116 +113,146 @@ curl -L https://github.com/phong28zk/ckforensics/releases/latest/download/ckfore
   -o /usr/local/bin/ckforensics && chmod +x /usr/local/bin/ckforensics
 ```
 
-Platforms: `linux-x64`, `linux-arm64`, `macos-arm64` (Apple Silicon), `windows-x64`
-
-> Intel Mac users: build from source — `bun build --compile --target=bun-darwin-x64 src/cli/index.ts --outfile ckforensics`
-
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Ingest all sessions from ~/.claude/projects/
-ckforensics ingest
+ckforensics ingest                         # populate DB (~20s for 1000+ jsonl)
+ckforensics summary                        # weekly totals
+ckforensics audit --last                   # last session manifest
+ckforensics map --last --top 10            # context heatmap
+ckforensics suggest --last                 # skill recommendations
+ckforensics doctor                         # health check
+```
 
-# 2. Summarize recent sessions (default 7 days)
-ckforensics summary
-ckforensics summary --days 1          # today
-ckforensics summary --days 30         # month
+**Recommended cron** (hourly auto-ingest):
 
-# 3. List recent sessions
-ckforensics sessions --limit 10
+```bash
+(crontab -l 2>/dev/null; echo "0 * * * * $(which ckforensics) ingest >> ~/.local/state/ckforensics/logs/ingest.log 2>&1") | crontab -
+```
 
-# 4. Audit the most recent session (markdown manifest)
-ckforensics audit --last
-ckforensics audit <session-id> --out review.md
+---
 
-# 5. Redact secrets from a file before sharing
-ckforensics redact review.md --in-place
+## ClaudeKit integration
 
-# 6. Export for scripting
-ckforensics export summary --format json | jq
-ckforensics export sessions --format csv --out sessions.csv
+When installed, `/ck:forensics` is available inside Claude Code:
 
-# 7. Health check
-ckforensics doctor
+```
+You: "show me last session cost"
+Claude: [auto-invokes /ck:forensics → reads SKILL.md → runs ckforensics audit --last]
+Claude: "Last session was 18h, $1102 API-equivalent. Top files: ..."
 ```
 
-> DB stored at XDG-compliant path (mode `0600`):
-> - Linux: `~/.local/share/ckforensics/store.db`
-> - macOS: `~/Library/Application Support/ckforensics/store.db`
-> - Windows: `%APPDATA%\ckforensics\store.db`
->
-> Nothing leaves your machine. Run `ckforensics path` to see resolved paths.
+**Triggers** (skill description picks these up):
+- "what did Claude touch this session"
+- "show me last session cost"
+- "where did my tokens go"
+- "audit last session"
+- "what skill should I have used"
+- `/ck:forensics summary` / `/ck:forensics audit` / etc
 
-### About cost numbers
+The skill ships with 3 workflows:
+- **`workflow-eod.md`** — end-of-day session review
+- **`workflow-pre-commit.md`** — generate commit message + redact before commit
+- **`workflow-weekly-retro.md`** — Sunday retrospective
 
-Cost shown is **API-rate equivalent** computed from token counts × Anthropic published prices ([Nov 2025 snapshot](https://platform.claude.com/docs/en/about-claude/pricing)).
+---
 
-- **API users:** approximates your actual bill (±10-30% for cache-pricing edge cases)
-- **Subscription users (Pro / Max / Team):** flat plan fee covers this; treat the number as **"value extracted"** from your subscription
+## Storage
 
-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.
+DB at XDG-compliant path (mode `0600`):
 
----
+| OS | Path |
+|----|------|
+| Linux | `~/.local/share/ckforensics/store.db` |
+| macOS | `~/Library/Application Support/ckforensics/store.db` |
+| Windows | `%APPDATA%\ckforensics\store.db` |
 
-## Screenshots
+Logs (daily-rotated):
 
-```
-[ terminal recording placeholder — see docs/demo.gif once available ]
-```
+| OS | Path |
+|----|------|
+| Linux | `~/.local/state/ckforensics/logs/` |
+| macOS | `~/Library/Logs/ckforensics/` |
+| Windows | `%LOCALAPPDATA%\ckforensics\Logs\` |
+
+**Nothing leaves your machine.** No telemetry. No cloud sync. Run `ckforensics path` to see resolved paths.
 
 ---
 
 ## Feature Matrix
 
-| Feature | ckforensics | ccusage | Native CC |
-|---------|:-----------:|:-------:|:---------:|
+| Feature | ckforensics | ccusage | Native CC `/usage` |
+|---------|:-----------:|:-------:|:--------------------:|
 | Local SQLite storage | ✅ | ✅ | ❌ |
-| Version-aware cost pricing | ✅ | 🟡 | ✅ (live only) |
-| Token usage analytics | ✅ | ✅ | ❌ |
-| Secret redaction (9 rules) | ✅ | ❌ | ❌ |
+| Token usage analytics | ✅ | ✅ | ✅ (live only) |
+| Version-aware cost pricing | ✅ | 🟡 | ✅ |
+| Subagent cost forensics (recursive) | ✅ | ❌ | ❌ |
+| Context window heatmap | ✅ | ❌ | ❌ |
+| Pre-compact simulation | ✅ | ❌ | ❌ |
+| Skill recommendation engine | ✅ | ❌ | ❌ |
 | Session change manifest (diff + reasoning) | ✅ | ❌ | ❌ |
-| Subagent attribution | ✅ | ❌ | ❌ |
-| Markdown / JSON / CSV export | ✅ | ❌ | ❌ |
-| Offline / no telemetry | ✅ | ✅ | ✅ |
+| Secret redaction (9 rules) | ✅ | ❌ | ❌ |
+| Markdown / JSON / CSV export | ✅ | 🟡 | ❌ |
+| Offline, zero telemetry | ✅ | ✅ | ✅ |
 | Cross-platform binaries | ✅ | ❌ | ✅ |
+| ClaudeKit skill bundled | ✅ | ❌ | ❌ |
 
 ---
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `ingest` | Parse JSONL files → SQLite |
-| `summary` | Token + cost summary for a time range |
-| `audit` | Detect secrets / anomalies in a session |
-| `export` | Output session as Markdown or JSON |
-| `redact` | Strip secrets from JSONL in-place |
-| `sessions` | List sessions with metadata |
-| `path` | Show DB path and stats |
-| `doctor` | Verify DB integrity and schema version |
+| Command | Purpose |
+|---------|---------|
+| `ingest` | Parse JSONL → SQLite (idempotent + incremental, optional `--watch`) |
+| `summary` | Token + cost rollup over rolling window (default 7d) |
+| `sessions` | List sessions with cost, duration, model |
+| `audit` | Per-session manifest: diffs + reasoning + subagent breakdown |
+| `map` | Context-window heatmap by category, snapshot/diff/pin |
+| `suggest` | Skill recommendations from detected tool patterns |
+| `skills` | Browse ClaudeKit skill catalog with usage stats |
+| `export` | Pipe-friendly export (markdown, JSON, CSV) |
+| `redact` | Strip 9 secret patterns from a file |
+| `doctor` | Health check (DB, paths, schema version, log activity) |
+| `path` | Show all resolved file system paths |
+
+Run `ckforensics <cmd> --help` for flags.
 
 ---
 
-## Architecture
-
-See [docs/architecture.md](docs/architecture.md) — module overview and data-flow diagram.
+## About cost numbers
 
-## Threat Model
+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)).
 
-See [docs/threat-model.md](docs/threat-model.md) — privacy stance, redaction guarantees, and known gaps.
+- **API users:** approximates your actual bill (±10-30% for cache-pricing edge cases)
+- **Subscription users (Pro / Max / Team):** flat plan fee covers this — treat the number as **"value extracted"** from your subscription
 
-## Schema
+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.
 
-See [docs/jsonl-schema-v1.md](docs/jsonl-schema-v1.md) — reverse-engineered Claude Code JSONL event types.
+---
 
-## Contributing
+## Documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, PR checklist, fixture contribution flow.
+| Doc | Topic |
+|-----|-------|
+| [docs/architecture.md](docs/architecture.md) | Module overview, data flow |
+| [docs/threat-model.md](docs/threat-model.md) | Privacy stance, redaction guarantees |
+| [docs/jsonl-schema-v1.md](docs/jsonl-schema-v1.md) | Reverse-engineered JSONL event types |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, PR checklist, fixture rules |
+| [ROADMAP.md](ROADMAP.md) | v0.1.x → v0.6+ feature plans |
+| [CHANGELOG.md](CHANGELOG.md) | Version history |
 
 ---
 
 ## License
 
 MIT — [LICENSE](LICENSE) — Copyright (c) 2026 phong28zk
+
+---
+
+## Acknowledgements
+
+- [ClaudeKit](https://github.com/phong28zk) ecosystem for the `/ck:*` skill pattern
+- [Anthropic](https://anthropic.com) for Claude Code + the public JSONL transcript format
+- [Bun](https://bun.sh) for single-binary compilation that makes cross-platform distribution painless

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckforensics",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "module": "index.ts",
   "type": "module",
   "bin": {
@@ -16,6 +16,8 @@
   "files": [
     "bin/",
     "scripts/postinstall.js",
+    "scripts/install-claudekit-skill.js",
+    ".claude/skills/",
     "README.md",
     "LICENSE"
   ],

package/scripts/install-claudekit-skill.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * install-claudekit-skill.js — Install the bundled `/ck:forensics` skill into
+ * the user's ClaudeKit skill directory (`~/.claude/skills/ckforensics/`).
+ *
+ * Called from postinstall.js. Designed to be silent on success and never
+ * fail the parent install — skill is a nice-to-have, not a hard dependency.
+ *
+ * Behavior:
+ *  - Copies `<pkg>/.claude/skills/ckforensics/` to `~/.claude/skills/ckforensics/`.
+ *  - Skip when source dir missing (e.g. dev install without the bundle).
+ *  - Skip on opt-out: `CKFORENSICS_SKIP_SKILL_INSTALL=1`.
+ *  - Existing skill dir is overwritten (idempotent re-install / version upgrade).
+ *  - Warnings to stderr only; never exits non-zero.
+ */
+
+import { existsSync, mkdirSync, cpSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, "..");
+const SKILL_SOURCE = join(PKG_ROOT, ".claude", "skills", "ckforensics");
+const SKILL_TARGET = join(homedir(), ".claude", "skills", "ckforensics");
+
+function log(msg) {
+  // Single-line dim format to fit cleanly in npm install output
+  process.stderr.write(`[ckforensics:skill] ${msg}\n`);
+}
+
+function shouldSkip() {
+  // Explicit opt-out
+  if (process.env.CKFORENSICS_SKIP_SKILL_INSTALL === "1") {
+    log("skipped via CKFORENSICS_SKIP_SKILL_INSTALL=1");
+    return true;
+  }
+  // Source missing — dev install or trimmed tarball
+  if (!existsSync(SKILL_SOURCE)) {
+    log(`skill source not bundled (${SKILL_SOURCE}); skipping`);
+    return true;
+  }
+  return false;
+}
+
+function copySkill() {
+  // Ensure parent dir exists; cpSync recursive handles the rest.
+  mkdirSync(dirname(SKILL_TARGET), { recursive: true });
+
+  // Detect upgrade vs first install for friendlier message
+  const existing = existsSync(SKILL_TARGET);
+  cpSync(SKILL_SOURCE, SKILL_TARGET, {
+    recursive: true,
+    force: true,
+    // Don't overwrite if user has customised it (mtime-based heuristic)
+    // — but that's risky and confusing. For now: always overwrite, matches
+    // CLI versioning semantics (skill version pinned to CLI version).
+  });
+
+  const action = existing ? "updated" : "installed";
+  log(`${action} skill at ${SKILL_TARGET}`);
+  log("activate next Claude Code session: /ck:forensics");
+}
+
+try {
+  if (shouldSkip()) {
+    process.exit(0);
+  }
+  copySkill();
+} catch (err) {
+  // Never fail parent install over skill copy
+  log(`warning: skill install failed (${err.message}); continuing`);
+  process.exit(0);
+}

package/scripts/postinstall.js

@@ -234,4 +234,19 @@ async function main() {
   console.log(`[ckforensics] Run: ckforensics --help`);
 }
 
-main().catch((e) => fatal(String(e)));
+async function installSkill() {
+  // Best-effort: invoke the dedicated skill installer module. Failures here
+  // never block the binary install. Module handles its own opt-out + missing-
+  // source cases.
+  try {
+    await import("./install-claudekit-skill.js");
+  } catch (err) {
+    process.stderr.write(
+      `[ckforensics:skill] warning: failed to load skill installer (${err.message})\n`
+    );
+  }
+}
+
+main()
+  .then(installSkill)
+  .catch((e) => fatal(String(e)));