inspecto 1.1.0 → 1.1.2

package/README.md

@@ -6,12 +6,97 @@
 
 **Claude Code session quality analyzer — grade sessions, detect regressions, catch cache bugs.**
 
-> CLI to grade Claude Code sessions — 750+ weekly downloads in first week.
+> CLI to grade Claude Code sessions — 915+ total downloads.
 
+---
+
+## What's New in v1.1.0
+
+915+ downloads in. Thank you. Here's everything that shipped.
+
+### 5 new quality metrics — 7 → 12
+
+| # | Metric | What it measures |
+|---|---|---|
+| **M8** | Subagent overhead | Whether Claude is delegating work to subagents efficiently — and whether those subagents are doing meaningful work |
+| **M9** | Tool error rate | How often Claude's tool calls return errors. High rates mean Claude is calling tools with bad arguments or on paths that don't exist |
+| **M10** | Thinking utilization | Whether extended thinking is actually being used on turns that warrant it. Low utilization on complex sessions often predicts high retry density |
+| **M11** | MCP usage | Informational count of MCP tool calls (web search, web fetch, custom servers) per session |
+| **M12** | Session cost | Estimated USD cost from real token usage — output, cache creation, and cache reads, priced at current Sonnet rates |
+
+All 12 metrics are pure functions of your local session files. No data leaves your machine.
+
+### Watch mode
+
+```bash
+npx inspecto watch
+```
+
+Streams live metric updates as Claude Code writes to the active session. Grade updates every time a new assistant turn lands. Hit Ctrl-C to exit.
+
+### Per-project config
+
+Drop `.inspecto.json` in your repo root to override thresholds and weights for your team:
+
+```json
+{
+  "thresholds": {
+    "tokensPerEdit": { "healthy": 8000, "warning": 15000 },
+    "sessionCost":   { "healthy": 5.00, "warning": 10.00 }
+  },
+  "weights": {
+    "cacheHitRate": 0.20,
+    "taskCompletion": 0.20
+  }
+}
+```
+
+Validate your config at any time:
+
+```bash
+npx inspecto config validate
+```
+
+### 2–3× faster trend and compare
+
+Computed grades are now cached in `~/.claude/inspecto-cache.db` (SQLite via `node:sqlite`). Cache key is `sha256(path:mtime)` — it invalidates automatically when Claude Code appends to a session. Re-runs over unchanged sessions skip parsing entirely. Up to 16 sessions are also parsed in parallel, so a 300-session history finishes in seconds instead of minutes.
+
+### CI exit codes
+
+`audit`, `trend`, and `cache-check` now exit 1 on failures. Drop into any pipeline:
+
+```bash
+npx inspecto trend --since 14d   # exits 1 on any regression
+npx inspecto audit --no-fail     # warns but never blocks
+```
 
+### Other additions
 
-> AMD's AI director manually analyzed 7,000 Claude Code sessions to prove it got worse.
-> `inspecto` automates that analysis for every developer.
+- **`inspecto list`** — discover your projects and sessions before running audit or compare. No more guessing project slugs for `--project`.
+- **CSV export** — `--format csv` on `audit` and `trend` for dashboards, spreadsheets, and log aggregators.
+- **Subagent session aggregation** — inspecto now reads subagent JSONL files (`{sessionId}/subagents/agent-*.jsonl`) and merges them into the parent session. Multi-agent sessions were previously graded with large gaps in tool calls and token usage.
+- **Format version detection** — inspecto now reads the `version` field on every JSONL record and warns when the format differs from what it was built against. Unknown record types are surfaced in the output rather than silently dropped.
+
+---
+
+## Why I built this
+
+In the 30 days before this tool existed:
+
+- **Apr 7, 2026** — A Reddit post about Claude Code's declining quality hit 1,060 upvotes
+- **Apr 6, 2026** — AMD's Director of AI filed a GitHub issue with data from 6,852 sessions proving Claude Code reads code 3x less before editing and rewrites entire files 2x more often than before
+- **Mar 31, 2026** — Claude Code's source leaked via npm, revealing 2 cache bugs that silently inflate costs 10-20x
+- **Mar 26, 2026** — Users on the $100/mo plan reported burning through limits in 90 minutes instead of 5 hours
+
+AMD's AI director manually analyzed 7,000 sessions to prove it got worse. That shouldn't require manual analysis.
+
+The tools that track token spending tell you *what* you used. `inspecto` tells you *whether it was worth it*.
+
+---
+
+## What it does
+
+`inspecto` reads the JSONL session logs Claude Code already writes to `~/.claude/projects/` and grades every session across 12 quality metrics — no API key, no telemetry, fully offline.
 
 | | `ccusage` | `claude-usage` | `Claude-Code-Usage-Monitor` | **`inspecto`** |
 |---|---|---|---|---|
@@ -29,10 +114,38 @@ The others answer *"how much did I spend?"*
 
 <img width="427" height="338" alt="Screenshot 2026-04-11 at 6 00 37 PM" src="https://github.com/user-attachments/assets/81777511-dd45-4ae0-8382-8e008dd98a7a" />
 
+### The 12 quality metrics
+
+Each metric is a pure function computed from your local session files.
+
+| # | Metric | What it detects | Healthy |
+|---|---|---|---|
+| **M1** | Reads-before-edit ratio | Claude editing without reading context first | ≥ 4.0 |
+| **M2** | Rewrite ratio | Full-file rewrites instead of surgical edits | ≤ 0.25 |
+| **M3** | Cache hit rate | Prompt cache bugs inflating token costs | ≥ 0.50 |
+| **M4** | Task completion | "I'll do X" promises without follow-through | ≥ 0.90 |
+| **M5** | Retry density | User repeating themselves (proxy for misunderstanding) | ≤ 0.10 |
+| **M6** | Tool diversity | Over-reliance on a narrow set of tools (Shannon entropy) | ≥ 0.60 |
+| **M7** | Tokens per edit | Token cost per productive action | ≤ 5,000 |
+| **M8** | Subagent overhead | Fraction of token work delegated to subagents | < 0.60 |
+| **M9** | Tool error rate | Rate of tool calls returning errors | ≤ 5% |
+| **M10** | Thinking utilization | Fraction of tool-using turns with extended thinking | ≥ 30% |
+| **M11** | MCP usage | Count of MCP tool turns (informational) | — |
+| **M12** | Session cost | Total estimated session cost | ≤ $2.00 |
+
+### How it works
+
+Claude Code writes one JSONL session file per conversation to `~/.claude/projects/{project}/{sessionId}.jsonl`. Each line is a JSON record — user messages, assistant responses (streamed as multiple chunks), tool calls, and tool results. Subagent sessions land in `{sessionId}/subagents/agent-*.jsonl`.
+
+`inspecto` streams these files line-by-line (never loading 100MB+ files into memory), merges streaming chunks by `message.id`, aggregates subagent turns into the parent session, extracts tool-use patterns and token usage, and computes the 12 metrics above.
+
+The composite grade is a weighted average mapped to a letter grade from **A+** to **F**.
 
 ---
 
-## Install
+## How to use it
+
+### Install
 
 ```bash
 npm install -g inspecto
@@ -48,8 +161,6 @@ Requires Node.js >= 22 (uses the built-in `node:sqlite` module). Works on macOS,
 
 ---
 
-## Usage
-
 ### Grade your most recent session
 
 ```bash
@@ -57,7 +168,7 @@ npx inspecto
 ```
 
 ```
-  inspecto v1.0.13 — Claude Code Session Quality Analyzer
+  inspecto v1.1.0 — Claude Code Session Quality Analyzer
 
   Session: 31f3f224 | my-app | 47 min | claude-opus-4-6
 
@@ -72,9 +183,23 @@ npx inspecto
   Retry density          0.08     ✓ healthy
   Tool diversity         0.52     ⚠ warning
   Tokens/useful-edit     3,218    ✓ healthy
+  Subagent overhead      0.41     ✓ healthy
+  Tool error rate        0.03     ✓ healthy
+  Thinking utilization   0.44     ✓ healthy
+  MCP usage              7        ✓ healthy
+  Session cost           $1.24    ✓ healthy
   ...
 ```
 
+### Watch a session live
+
+```bash
+npx inspecto watch
+npx inspecto watch --project my-app
+```
+
+Clears and re-renders the full audit report every time Claude Code writes a new turn. Useful during long sessions to catch degradation before it compounds.
+
 ### Detect regressions over time
 
 ```bash
@@ -124,15 +249,15 @@ npx inspecto compare --projects my-app,api-gateway,shared-lib
 
 ### Manage the grade cache
 
-`inspecto trend` and `inspecto compare` cache computed grade results in `~/.claude/inspecto-cache.db` so re-runs over the same sessions are near-instant. The cache is keyed by file path + mtime, so it invalidates automatically when Claude Code writes new data to a session.
-
 ```bash
 npx inspecto cache clear   # delete the cache file (~/.claude/inspecto-cache.db)
 ```
 
+`inspecto trend` and `inspecto compare` cache computed grades in `~/.claude/inspecto-cache.db`. The cache is keyed by file path + mtime and invalidates automatically when Claude Code writes new data.
+
 ---
 
-## CI integration
+### CI integration
 
 `inspecto` exits with a non-zero code when quality drops below acceptable thresholds:
 
@@ -143,7 +268,7 @@ npx inspecto cache clear   # delete the cache file (~/.claude/inspecto-cache.db)
 | `inspecto cache-check` | Any session has a cache anomaly |
 | `inspecto compare` | Never (comparison is informational) |
 
-Use `--no-fail` on any command to always exit 0 — useful for scripts that want the output without failing the pipeline:
+Use `--no-fail` to always exit 0:
 
 ```bash
 # In a pre-push hook — warn but don't block
@@ -158,9 +283,7 @@ npx inspecto audit --format csv --no-fail >> metrics.csv
 
 ---
 
-## Output formats
-
-All commands default to terminal output with color and tables. For scripting:
+### Output formats
 
 ```bash
 # Structured JSON
@@ -172,13 +295,13 @@ npx inspecto audit --format csv
 npx inspecto trend --format csv
 ```
 
-`audit --format csv` produces one row per metric: `name,value,status,label`
+`audit --format csv` — one row per metric: `name,value,status,label`
 
-`trend --format csv` produces one row per metric: `name,recentAvg,fullAvg,changePercent,status`
+`trend --format csv` — one row per metric: `name,recentAvg,fullAvg,changePercent,status`
 
 ---
 
-## Global options
+### Global options
 
 | Flag | Commands | Description |
 |---|---|---|
@@ -189,33 +312,13 @@ npx inspecto trend --format csv
 | `--project <name>` | `audit`, `trend`, `compare`, `list` | Filter to a specific project |
 | `--since <duration>` | `trend`, `cache-check` | Time range (e.g., `7d`, `14d`, `30d`) |
 | `--sessions` | `list` | Show sessions view instead of projects view |
+| `--interval <ms>` | `watch` | Polling interval fallback in ms (default: 2000) |
 
 ---
 
-## The 12 Quality Metrics
-
-Each metric is a pure function computed from your local session files. No data leaves your machine.
-
-| # | Metric | What it detects | Healthy |
-|---|---|---|---|
-| **M1** | Reads-before-edit ratio | Claude editing without reading context first | ≥ 4.0 |
-| **M2** | Rewrite ratio | Full-file rewrites instead of surgical edits | ≤ 0.25 |
-| **M3** | Cache hit rate | Prompt cache bugs inflating token costs | ≥ 0.50 |
-| **M4** | Task completion | "I'll do X" promises without follow-through | ≥ 0.90 |
-| **M5** | Retry density | User repeating themselves (proxy for misunderstanding) | ≤ 0.10 |
-| **M6** | Tool diversity | Over-reliance on a narrow set of tools (Shannon entropy) | ≥ 0.60 |
-| **M7** | Tokens per edit | Token cost per productive action | ≤ 5,000 |
-| **M8** | Subagent overhead | Fraction of turns delegated to subagents | < 0.60 |
-| **M9** | Tool error rate | Rate of tool calls returning errors | ≤ 5% |
-| **M10** | Thinking utilization | Fraction of turns using extended thinking | ≥ 30% |
-| **M11** | MCP usage | Count of MCP tool turns (informational) | — |
-| **M12** | Session cost | Total estimated session cost | ≤ $2.00 |
-
----
-
-## What to do about it
+### What to do about it
 
-Once inspecto shows you where your sessions are degrading, here's how to fix each metric:
+Once inspecto shows you where sessions are degrading, here's how to fix each metric:
 
 | Metric | Symptom | Fix |
 |---|---|---|
@@ -226,6 +329,7 @@ Once inspecto shows you where your sessions are degrading, here's how to fix eac
 | **Retry density high** | You're repeating yourself — Claude keeps misunderstanding | You're probably under-specifying. Provide a concrete example of the output you want in the first message. If retries persist across sessions, the root cause is usually a missing `CLAUDE.md` or a context window that's too wide. |
 | **Tool diversity low** | Claude over-relies on a narrow tool set (e.g. only Bash) | Prompt explicitly: *"Use the most specific tool available. Prefer Read over Bash for file reads. Prefer Edit over Write for modifications."* This is also a sign of a degraded model — track it over time with `inspecto trend`. |
 | **Tokens/edit high** | High token burn per productive action | Shorten your context. Close irrelevant files in the IDE, trim `CLAUDE.md` to essentials, and use `--project` to scope sessions to one repo at a time. |
+| **Subagent overhead high** | Subagents doing most of the work but graded separately | Run `inspecto audit` on the root session — it now aggregates subagent turns automatically. If overhead is still high, your orchestration prompts may be spawning agents that duplicate work. |
 | **Tool error rate high** | Claude's tool calls are frequently failing | Usually means Claude is passing bad arguments or calling tools on files that don't exist. Add stricter preconditions in `CLAUDE.md`: *"Verify a file exists before reading it. Verify a path before writing."* |
 | **Thinking utilization low** | Extended thinking is rarely being used | For complex tasks, prompt Claude to think before acting: *"Think carefully before making any changes."* Low thinking utilization often correlates with shallow analysis and increased retry density. |
 | **Session cost high** | Spending more than expected per session | Scope sessions narrowly — one task, one repo. Use `--project` to avoid scanning large unrelated projects. Frequent cache misses compound cost; check `cache-check` if cost spiked unexpectedly. |
@@ -234,29 +338,6 @@ Once inspecto shows you where your sessions are degrading, here's how to fix eac
 
 ---
 
-## How it works
-
-Claude Code writes one JSONL session file per conversation to `~/.claude/projects/{project}/{sessionId}.jsonl`. Each line is a JSON record — user messages, assistant responses (streamed as multiple chunks), tool calls, and tool results.
-
-`inspecto` streams these files line-by-line (never loading 100MB+ files into memory), merges streaming chunks by `message.id`, extracts tool-use patterns and token usage, and computes the 12 metrics above.
-
-The composite grade is a weighted average mapped to a letter grade from **A+** to **F**. Grades below **D+** (score < 67) trigger a non-zero exit code in CI mode.
-
----
-
-## Why this exists
-
-In the last 30 days before this tool was built:
-
-- **Apr 7, 2026** — A Reddit post about Claude Code's declining quality hit 1,060 upvotes
-- **Apr 6, 2026** — AMD's Director of AI filed a GitHub issue with data from 6,852 sessions proving Claude Code reads code 3x less before editing and rewrites entire files 2x more often than before
-- **Mar 31, 2026** — Claude Code's source leaked via npm, revealing 2 cache bugs that silently inflate costs 10-20x
-- **Mar 26, 2026** — Users on the $100/mo plan reported burning through limits in 90 minutes instead of 5 hours
-
-The tools that track token spending tell you *what* you used. `inspecto` tells you *whether it was worth it*.
-
----
-
 ## Development
 
 ```bash
@@ -272,11 +353,11 @@ Architecture:
 
 ```
 src/
-├── parser/        # Streaming JSONL reader + session builder (merges streaming chunks)
+├── parser/        # Streaming JSONL reader + session builder (merges streaming chunks, aggregates subagents)
 ├── metrics/       # 12 pure-function quality metrics + composite grader
 ├── anomaly/       # Baseline computation + regression detection + cache anomaly
 ├── reporter/      # Terminal (chalk + cli-table3), JSON, and CSV output modes
-├── commands/      # audit, trend, cache-check, compare, list
+├── commands/      # audit, trend, cache-check, compare, list, watch
 ├── cache/         # SQLite grade-result cache (node:sqlite, ~/.claude/inspecto-cache.db)
 ├── config/        # .inspecto.json config loader + per-metric threshold/weight overrides
 └── utils/         # Levenshtein, paths, duration parsing, formatting, concurrency helper
@@ -284,12 +365,14 @@ src/
 
 Key technical details:
 - **Streaming parse**: `readline` + `createReadStream` — never loads full files into memory
-- **Chunk deduplication**: Assistant responses come as multiple JSONL records sharing `message.id`; content blocks are merged and only the final chunk's `output_tokens` is used
-- **No external APIs**: All analysis is local. No network calls. Works offline
+- **Subagent aggregation**: discovers `{sessionId}/subagents/agent-*.jsonl`, tags each turn with `agentId`, and merges into the parent session's turn list
+- **Chunk deduplication**: assistant responses come as multiple JSONL records sharing `message.id`; content blocks are merged and only the final chunk's `output_tokens` is used
+- **No external APIs**: all analysis is local. No network calls. Works offline
 - **Real token cost**: `input_tokens` is always a streaming placeholder — actual input = `cache_read_input_tokens + cache_creation_input_tokens`
 - **Concurrency**: `trend` and `compare` parse up to 16 session files in parallel (semaphore-limited) so large histories don't block
 - **Grade cache**: computed `GradeResult` objects are persisted in `~/.claude/inspecto-cache.db` (SQLite via `node:sqlite`). Cache key = `sha256(path:mtime)`. Re-runs over unchanged sessions skip parsing entirely — typically 2–3× faster
 - **CI exit codes**: `audit` exits 1 on D/F grades, `trend` exits 1 on any regression, `cache-check` exits 1 on any anomaly. All suppressed by `--no-fail`
+- **Format resilience**: reads the `version` field on every JSONL record and warns when the format diverges from the expected version. Unknown record types are surfaced in output rather than silently dropped
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inspecto",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "inspecto — Claude Code session quality analyzer. Grade sessions, detect regressions, catch cache bugs.",
   "type": "module",
   "main": "./dist/index.js",