session-investigator
Investigate fast-agent session and history files to diagnose issues. Use when a session ended unexpectedly, when debugging tool loops, when correlating sub-agent traces with main sessions, or when analyzing conversation flow and timing. Covers session.json metadata, history JSON format, message structure, tool call/result correlation, and common failure patterns.
npx skills add evalstate/fast-agent --skill session-investigator --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 ```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..." } } ``` ### history\_<agent>.json ```json { "messages": [ { "role": "user|assistant", "content": [{"type": "text", "text": "..."}], "tool_calls": {"<id>": {"method": "tools/call", "params": {"name": "...", "arguments": {}}}}, "tool_results": {"<id>": {"content": [...], "isError": false}}, "channels": { "fast-agent-timing": [{"type": "text", "text": "{\"start_time\": ..., \"end_time\": ..., \"duration_ms\": ...}"}
- Session Directory Structure
- Key Files
- session.json
- history\<agent>.json
- Investigation Commands
- Basic inspection
- Tool call correlation
- Find specific tool calls
- Session Statistics
- LLM Call Stats
- Tool Execution Stats
- Session Timeline
- Sub-agent Stats
- Common Failure Patterns
Message count
jq '.messages | length' history_dev.json
Last N messages overview
jq '.messages[-5:] | .[] | {role, stop_reason, has_tool_calls: (.tool_calls != null), has_tool_results: (.tool_results != null)}' history_dev.json
View specific message
jq '.messages[227]' history_dev.json
Check tool call/result pairing
jq '.messages[-10:] | to_entries | .[] | {
Find all calls to a specific tool
jq '.messages | to_entries | .[] |What does the session-investigator skill do?
Investigate fast-agent session and history files to diagnose issues. Use when a session ended unexpectedly, when debugging tool loops, when correlating sub-agent traces with main sessions, or when analyzing conversation flow and timing. Covers session.json metadata, history JSON format, message structure, tool call/result correlation, and common failure patterns.
How do I install it?
Run `npx skills add evalstate/fast-agent --skill session-investigator --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From evalstate/fast-agent, a repository with 3,880 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.