| name | set:forensics |
| description | Forensic analysis of a completed orchestration run. Use this for post-run debugging, error triage, and digging into what an agent actually did inside a session — without dragging raw 300 KB jsonl transcripts into context. |
/set:forensics — Run forensics
Triage what failed in a completed orchestration run using filtered views over Claude Code session transcripts and orchestration logs.
WARNING — never read raw session jsonl files unbounded. A single session jsonl can exceed 300 KB and a run typically has 50+ sessions. Always go through the CLI's filtered views first; only fall back to raw Read on a specific line range when the CLI has narrowed the suspect.
Triage order
Always follow this sequence:
-
set-run-logs <run-id> discover — confirm the scope of resolved sources. Verify the main session dir and every -wt-<change> worktree dir was found, plus the orchestration dir.
-
set-run-logs <run-id> digest — get the error map. Aggregates tool errors, non-zero bash exits, stop-reason anomalies, user interrupts, permission denials, and crash suspects across every session. Output is grouped by change → session → tool with snippets.
-
set-run-logs <run-id> session <uuid> --errors-only — for each suspect session in the digest, view its tool-call timeline filtered to errors. Use the short UUID prefix (≥6 chars) from the digest. Only AFTER you've narrowed via this view should you read raw jsonl.
-
set-run-logs <run-id> grep <pattern> — targeted probe for a specific error signature across all sessions. Emits ONLY the matching message.content text (not raw jsonl lines), so it's safe to use in agent context. Default cap is 50 matches — pass --limit to raise.
-
set-run-logs <run-id> orchestration — cross-reference timing. Shows per-change dispatch counts, last gate status, terminal status, gate-outcome counts. Use this to map a suspect session back to its orchestration timeline (when it dispatched, which gate triggered, what the terminal status was).
-
Raw jsonl as last resort. If the CLI's filtered views still leave a question unanswered, locate the specific jsonl from discover output and Read only the line range you need. Never Read a session jsonl without an offset/limit.
Common subcommand options
--json — emit JSON instead of markdown (for piping to jq or programmatic consumers).session --tool <name> — filter a session timeline to a single tool (e.g. --tool Bash).grep -i — case-insensitive search.grep --tool <name> — restrict grep to one tool's tool_use / tool_result blocks.grep --limit <N> — raise the default 50-match cap (use sparingly to protect context).
When to use
- After any orchestration run that didn't merge cleanly.
- When the user asks "what happened in run X?" / "why did change Y fail?" / "did agent Z get stuck?".
- Before reading any session jsonl by hand.
- When investigating a finding from the verify gate — find the agent session that produced the failing commit.
When NOT to use
- For an in-flight run — the sentinel owns live monitoring; this targets completed runs.
- For cross-run comparison — use
set-compare instead.
- For project-type-specific analysis — this CLI is project-agnostic.
Quick reference
set-run-logs <run-id> discover
set-run-logs <run-id> digest
set-run-logs <run-id> session <uuid> --errors-only
set-run-logs <run-id> grep <pattern> [--tool <name>]
set-run-logs <run-id> orchestration
Pair every drill-down with the orchestration view to align session events with dispatch / gate timing. Don't read raw jsonl until the CLI has narrowed the suspect.
