/session-debug

name: session-debug
description: >
  Debug a specific session by inspecting its full event chain (PreToolUse,
  PostToolUse, Stop, SubagentStop, Compaction, APIError, TurnDuration,
  Notification events), agent hierarchy (recursive parent/child tree with
  subagent_type and depth), token usage with compaction baselines, workflow
  intelligence data (orchestration DAG, error propagation by depth), and
  session metadata (thinking_blocks, turn_count, total_turn_duration_ms).

Session Debug

Debug and inspect a Claude Code session from Agent Monitor data.

Input

The user provides: **$ARGUMENTS**

This may be:

• A session ID to debug
• "latest" or "last" for the most recent session
• "errors" to find and debug the most recent errored session

Procedure

1. **Identify the target session**:

• If session ID given: `GET /api/sessions/{id}` from `http://localhost:4820`
• If "latest": `GET /api/sessions?limit=1` (default sort: most recently updated first)
• If "errors": `GET /api/sessions?limit=10&status=error`

2. **Collect full session data**:

• Session metadata: status, model, cwd, timestamps, duration
• Events: `GET /api/events?session_id={session_id}` — full event timeline
• Agents: `GET /api/agents?session_id={session_id}` — all agents in session
• Cost: `GET /api/pricing/cost/{session_id}`

3. **Analyze the session**:

Session Lifecycle

• Start time → first event → last event → end time
• Status transitions (active → working → completed/error)
• Total duration and active-vs-idle time

Event Chain Analysis

• Chronological event list with timestamps and durations
• Identify the **critical path** (longest chain of dependent events)
• Flag events that took unusually long
• Highlight error events with full error context

Agent Inspection

• List all agents: type, task, status, duration
• Subagent tree visualization (parent → children)
• Agents that failed and their last known state
• Agent switching patterns (when and why new agents spawned)

Tool Execution Trace

• Every tool invocation in order with: tool name, duration, success/failure
• Failed tool calls with error messages
• Tool retry patterns (same tool called multiple times)

Anomaly Detection

• Events out of expected order
• Gaps in event timeline (>30s with no events)
• Duplicate events or agent states
• Token usage spikes (compaction indicators)

4. **Diagnosis**:

• Root cause hypothesis (if errors present)
• Contributing factors
• Remediation suggestions

Output Format

Present as a debug report with:

• Session summary header (ID, status, model, duration, cost)
• Color-coded timeline (✅ success, ❌ error, ⚠️ warning, ℹ️ info)
• Agent tree diagram
• Diagnosis section with numbered findings