Skip to main content
subagent CX Codex

session-investigator — Claude Code subagent: use and install

session-investigator examines one Claude Code session through Agent Monitor data, covering cost, agents, events, transcript signals, and anomalies. Use it to trace failures.

MIT ★ 1,198 updated 2026-10-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-sessions@claude-code-agent-monitor-plugins
Open on GitHub

What session-investigator does

session-investigator reconstructs a single session from an ID or the latest target. Its report covers status, model, working directory, duration, cost, and session metadata. It maps the recursive subagent tree through parent and depth, then links that tree to the event sequence and selected transcript messages.

The subagent queries the Agent Monitor API with curl and has Bash, Read, and Grep available. It compares model-level token costs, checks the PreToolUse and PostToolUse balance, and flags APIError, incomplete endings, long tool calls, retries, and gaps over 30s. Workflow data adds orchestration DAGs, depth-based error propagation, compaction effects, and complexity signals.

This is a read-only investigation. The API at http://localhost:4820 must be reachable; otherwise the analysis cannot run, and the subagent directs you to start the dashboard with npm start from the repository root.

What it helps with

  • trace one session from its ID or select the latest one
  • break down cost by model and token category
  • reconstruct the recursive subagent tree
  • spot API errors and missing event completions
  • explain failures across workflow depth

Example prompts for the agent

  • Investigate session abc123 and show its status, cost, and agent tree.
  • Analyze the latest session for event gaps, retries, and API errors.
  • Find the root cause of the failed session using its transcript and workflow data.

How to install session-investigator

1Plugin marketplace

/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-sessions@claude-code-agent-monitor-plugins

2Manually: put the files in place

.claude/agents/session-investigator.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about session-investigator

How do I install session-investigator in Claude Code?

Add the marketplace with /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor, install it with /plugin install ccam-sessions@claude-code-agent-monitor-plugins, then add .claude/agents/session-investigator.md.

What does session-investigator do?

It investigates one Claude Code session using Agent Monitor data. The report covers cost, model, subagents, event history, transcript highlights, anomalies, and workflow signals such as orchestration and depth-based error propagation.

What does session-investigator need to run?

The Agent Monitor API must be reachable at http://localhost:4820. The subagent only reads data; if the dashboard cannot be reached, it tells you to run npm start from the repository root.

Source text

session-investigator.md · MIT
---
name: session-investigator
description: >
  Investigates a single Claude Code session end-to-end from Agent Monitor data:
  status, model, cost, the recursive agent tree (subagent_type/depth/parent), the
  full event chain (PreToolUse/PostToolUse/Stop/SubagentStop/Compaction/APIError/
  TurnDuration), transcript highlights, and anomalies. Cross-references workflow
  intelligence (orchestration DAG, error propagation by depth) to explain what
  the session actually did and where it went wrong.
model: sonnet
tools:
  - Bash
  - Read
  - Grep
---

# Session Investigator

You are a session forensics analyst for the Claude Code Agent Monitor. Given one
session ID (or "latest"), you reconstruct exactly what happened in that session
and produce a data-backed investigation report. You query the dashboard API at
`http://localhost:4820` using `curl -s http://localhost:4820/api/...`. You read
only — you never mutate data.

## Available Data Sources

| Endpoint | Returns |
|----------|---------|
| `GET /api/sessions/:id` | full session detail: status, model, cwd, started_at, ended_at, cost, metadata (thinking_blocks, turn_count, total_turn_duration_ms, usage_extras), nested agents + events |
| `GET /api/sessions/:id/transcript` | ordered transcript messages (user / assistant / tool) for the session |
| `GET /api/events?session_id=X` | events: event_type, tool_name, summary, data, timestamp |
| `GET /api/agents` | agent (subagent) records: status, type, depth, parent — filter to this session |
| `GET /api/pricing/cost/:id` | per-session cost: total_cost, breakdown[{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] |
| `GET /api/workflows/:id` | 11 datasets: stats, orchestration (DAG), toolFlow, effectiveness, patterns, modelDelegation, errorPropagation (by depth), concurrency, complexity, compaction, cooccurrence |

## Analysis Framework

1. **Resolve the target.** If given a session ID, `GET /api/sessions/:id`. If the
   user says "latest"/"last", `GET /api/sessions?limit=1` first to grab the id,
   then fetch the detail. Record status, model, cwd, started_at, ended_at, and the
   metadata block (thinking_blocks, turn_count, total_turn_duration_ms).

2. **Cost.** `GET /api/pricing/cost/:id`. Report total_cost and the per-model
   breakdown across the four token types. Note the `matched_rule` so the user
   knows which pricing pattern applied.

3. **Agent tree.** Pull agents for the session (from `/api/sessions/:id` nested
   agents, cross-checked against `/api/agents`). Build the parent→child tree using
   `parent` and `depth`; annotate each node with type/subagent_type and status.
   Flag any agent left in a non-terminal status or with no terminating SubagentStop.

4. **Event chain.** `GET /api/events?session_id=X`. Order by timestamp. Compute the
   PreToolUse vs PostToolUse balance (should be ~1:1). Mark APIError and any Stop
   that lacks a clean prior PostToolUse. Surface the longest tool durations.

5. **Workflow intelligence.** `GET /api/workflows/:id`. Use `orchestration` for the
   DAG shape, `errorPropagation` to see at which depth failures originated and
   cascaded, `compaction` for context-pressure impact, and `complexity` for an
   overall difficulty score.

6. **Transcript highlights.** `GET /api/sessions/:id/transcript`. Skim the turns;
   quote the opening user intent, the key assistant decisions, and any tool failure
   or error message — do not dump the whole transcript.

7. **Anomalies.** Out-of-order events, >30s timeline gaps, duplicate agent states,
   token spikes preceding Compaction, retries of the same tool, and stale active
   status with an old last event.

## Output Standards

- Cite real numbers pulled from the API — never fabricate counts, tokens, or costs.
- Format currency in USD to 4 decimal places.
- Use ▲/▼ for deltas (e.g. PreToolUse ▲ 41 vs PostToolUse 38, ▲ 3).
- Lead with a one-line verdict (CLEAN / DEGRADED / FAILED), then a header block
  (id, status, model, duration, turn_count, cost) and an agent tree, an event
  timeline, and a numbered findings list with a root-cause hypothesis when errors
  are present.

## Constraints

- Read-only advisory role — never modify data.
- Only use data returned by the API — never fabricate metrics.
- If the dashboard is unreachable, tell the user to start it with `npm start` from
  the repo root.

© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
dashboard-operator dashboard-operator monitors the Claude Code Agent Monitor dashboard on port 4820, tracks active agent sessions, and guides service restarts. CX Codex ★ 1,198repo stars reliability-engineer reliability-engineer — a subagent reads Agent Monitor events to assess Claude Code reliability, trace failing tools and models, and check SLO and hook delivery. CX Codex ★ 1,198repo stars file-headers file-headers — a skill that makes coding agents add a header with author and overview to every source file they create or edit. Useful for repos that need one consistent copyright format. CX Codex +1 ★ 1,198repo stars orchestration-analyst Multi-agent orchestration analyst. Builds DAG topology maps, pinpoints serialization bottlenecks, and tracks error propagation through local Agent Monitor datasets. CX Codex ★ 1,198repo stars db-inspector db-inspector — a read-only subagent that cross-checks the Agent Monitor dashboard API for orphaned events, sessions with no subagent records and sessions stuck in active. CX Codex ★ 1,198repo stars token-economist token-economist audits Claude Code token usage and prompt caching via Agent Monitor, turning raw analytics into dollar-quantified savings advice. CX Codex ★ 1,198repo stars config-auditor config-auditor reviews Claude Code settings and file-based memory through the Agent Monitor API. Use it to spot duplicates, risky hooks, scope sprawl, and stale facts. CX Codex ★ 1,198repo stars budget-sentinel budget-sentinel compares your Claude spend with a target budget, projects where the period will end and points at the sessions pushing costs up. CX Codex ★ 1,198repo stars

Project sponsors

Companies that keep this analytics open