Session Investigator

When fast-agent sessions go sideways, this is your forensics kit. It walks you through the session directory structure, shows you how to parse session.json and history files, and gives you jq commands to correlate tool calls with results, track timing across LLM and tool invocations, and spot common failure patterns like unanswered tool calls or duplicate user messages. The real value is in the investigation recipes: finding tool loops, calculating session statistics, matching sub-agent traces to main sessions via monotonic clock values. If you've ever stared at a 300-message history wondering where things went wrong, these jq snippets will save you an hour of manual JSON archaeology.

GitHub stars: 3.8K
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add evalstate/fast-agent --skill session-investigator --agent claude-code

Installs into .claude/skills of the current project.

Files

Session Investigator

Diagnose fast-agent session issues by examining session and history files.

Session Directory Structure

Sessions are stored in .fast-agent/sessions/<session-id>/:

2601181023-Kob2h3/
├── session.json              # Session metadata
├── history_<agent>.json      # Current agent history
└── history_<agent>_previous.json  # Previous save (rotation backup)

Session IDs encode creation time: YYMMDDHHMM-<random> (e.g., 2601181023 = 2026-01-18 10:23).

Key Files

session.json

{
  "name": "2601181023-Kob2h3",
  "created_at": "2026-01-18T10:23:24.116526",
  "last_activity": "2026-01-18T10:39:42.873467",
  "history_files": ["history_dev_previous.json", "history_dev.json"],
  "metadata": {
    "agent_name": "dev",
    "first_user_preview": "is it possible to override..."
  }
}