inspecto 1.0.11 → 1.0.13

package/README.md

@@ -27,7 +27,7 @@ The others answer *"how much did I spend?"*
 
 `inspecto` answers: **"Is Claude Code getting worse for me — and can I prove it?"**
 
-<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" />
+<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" />
 
 
 ---
@@ -57,7 +57,7 @@ npx inspecto
 ```
 
 ```
-  inspecto v1.0.0 — Claude Code Session Quality Analyzer
+  inspecto v1.0.13 — Claude Code Session Quality Analyzer
 
   Session: 31f3f224 | my-app | 47 min | claude-opus-4-6
 
@@ -72,6 +72,7 @@ npx inspecto
   Retry density          0.08     ✓ healthy
   Tool diversity         0.52     ⚠ warning
   Tokens/useful-edit     3,218    ✓ healthy
+  ...
 ```
 
 ### Detect regressions over time
@@ -90,6 +91,31 @@ npx inspecto cache-check
 
 On March 31, 2026, the leaked Claude Code source revealed two cache bugs that silently inflate token costs 10-20x. This command detects sessions where the cache hit rate is suspiciously low.
 
+### Discover projects and sessions
+
+```bash
+# List all projects with session counts and last-active dates
+npx inspecto list
+
+# Show the 20 most recent sessions across all projects
+npx inspecto list --sessions
+
+# Show all sessions for a specific project
+npx inspecto list --project my-app
+```
+
+```
+  Projects (9 found)
+
+  ─────────────────────────────────────────────
+    Project            Sessions   Last active
+  ─────────────────────────────────────────────
+    my-app             47         2026-06-08
+    api-gateway        12         2026-06-01
+    shared-lib          3         2026-05-28
+  ─────────────────────────────────────────────
+```
+
 ### Compare projects
 
 ```bash
@@ -104,18 +130,69 @@ npx inspecto compare --projects my-app,api-gateway,shared-lib
 npx inspecto cache clear   # delete the cache file (~/.claude/inspecto-cache.db)
 ```
 
-### Global options
+---
+
+## CI integration
 
-| Flag | Description |
+`inspecto` exits with a non-zero code when quality drops below acceptable thresholds:
+
+| Command | Exits 1 when… |
 |---|---|
-| `--json` | Output structured JSON (for CI, piping, scripts) |
-| `--data-dir <path>` | Custom Claude data directory (default: `~/.claude`) |
-| `--project <name>` | Filter to a specific project |
-| `--since <duration>` | Time range (e.g., `7d`, `14d`, `30d`) |
+| `inspecto audit` | Overall grade is D or F (score < 67) |
+| `inspecto trend` | Any metric has status `regression` |
+| `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:
+
+```bash
+# In a pre-push hook — warn but don't block
+npx inspecto audit --no-fail
+
+# In CI — fail the build on regressions
+npx inspecto trend --since 14d
+
+# Export metrics for a dashboard without blocking
+npx inspecto audit --format csv --no-fail >> metrics.csv
+```
+
+---
+
+## Output formats
+
+All commands default to terminal output with color and tables. For scripting:
+
+```bash
+# Structured JSON
+npx inspecto audit --json
+npx inspecto trend --json
+
+# CSV (RFC 4180)
+npx inspecto audit --format csv
+npx inspecto trend --format csv
+```
+
+`audit --format csv` produces one row per metric: `name,value,status,label`
+
+`trend --format csv` produces one row per metric: `name,recentAvg,fullAvg,changePercent,status`
+
+---
+
+## Global options
+
+| Flag | Commands | Description |
+|---|---|---|
+| `--json` | all | Output structured JSON |
+| `--format <fmt>` | `audit`, `trend` | Output format: `json` or `csv` |
+| `--no-fail` | `audit`, `trend`, `cache-check`, `compare` | Always exit 0 |
+| `--data-dir <path>` | all | Custom Claude data directory (default: `~/.claude`) |
+| `--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 |
 
 ---
 
-## The 7 Quality Metrics
+## The 12 Quality Metrics
 
 Each metric is a pure function computed from your local session files. No data leaves your machine.
 
@@ -128,6 +205,11 @@ Each metric is a pure function computed from your local session files. No data l
 | **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 |
 
 ---
 
@@ -144,6 +226,9 @@ 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. |
+| **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. |
 
 **The single highest-leverage fix:** a well-structured `CLAUDE.md`. It front-loads context so Claude reads less at runtime, forces it to follow project conventions, and survives session restarts without re-explaining yourself.
 
@@ -153,9 +238,9 @@ Once inspecto shows you where your sessions are degrading, here's how to fix eac
 
 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 7 metrics above.
+`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**.
+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.
 
 ---
 
@@ -188,11 +273,12 @@ Architecture:
 ```
 src/
 ├── parser/        # Streaming JSONL reader + session builder (merges streaming chunks)
-├── metrics/       # 7 pure-function quality metrics + composite grader
+├── metrics/       # 12 pure-function quality metrics + composite grader
 ├── anomaly/       # Baseline computation + regression detection + cache anomaly
-├── reporter/      # Terminal (chalk + cli-table3) and JSON output modes
-├── commands/      # audit, trend, cache-check, compare
+├── reporter/      # Terminal (chalk + cli-table3), JSON, and CSV output modes
+├── commands/      # audit, trend, cache-check, compare, list
 ├── 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
 ```
 
@@ -203,6 +289,7 @@ Key technical details:
 - **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`
 
 ---