session-reader

Parse and analyze pi agent session JSONL files for execution insights.

1|Updated Feb 22, 2026

Search Tags:#debugging #logs #analysis #session #jsonl #pi agent

Ready to run

npx skills add https://github.com/sergical/pi-config --skill session-reader-sergical

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: session-reader
Source: https://github.com/sergical/pi-config/tree/main/skills/session-reader
Command: npx skills add https://github.com/sergical/pi-config --skill session-reader-sergical

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill helps you understand and analyze the detailed execution history of pi agent sessions, making it easier to debug, review, and learn from past interactions.

Core Features & Use Cases

Session Overview: Get a high-level summary of session metadata, turns, and costs.
Detailed Analysis: View conversation history, tool calls, tool results, and subagent executions.
Cost Tracking: Analyze token usage and costs per turn and per subagent.
Use Case: After a complex task failed, use this Skill to read the session log, identify where the agent went wrong, and understand the cost incurred during the failed attempt.

Quick Start

Use the session-reader skill to get an overview of the session file located at ~/.pi/agent/sessions/my-project/2023-10-27T10-00-00Z_abc.jsonl.

Frequently Asked Questions about session-reader

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I analyze pi agent session logs to debug execution failures?▼

To analyze pi agent session logs, parse the JSONL files to review conversation history, tool calls, and subagent executions. This reveals where the agent went wrong and details the cost incurred during the failed attempt.

What is the best way to get a high-level overview of a pi agent session?▼

The best way to get a session overview is to parse the JSONL file for session metadata, total turns, and cost breakdowns. This provides a structured summary of agent execution and overall token usage.

Can I track token costs and usage per turn in agent session JSONL files?▼

Yes, you can track token costs and usage per turn by analyzing the JSONL session logs. The cost breakdown mode extracts detailed token usage metrics for each turn and subagent run.

How do I extract subagent run information from agent session logs?▼

To extract subagent run information, parse the session JSONL files using a dedicated analysis mode. This surfaces detailed logs of subagent executions, including their specific tool calls and results.

Does session analysis work with standard JSONL files for reviewing tool calls?▼

Yes, session analysis works directly with standard JSONL files to review detailed tool calls and tool results. It structures the raw logs into readable formats for debugging and reviewing agent behavior.

What are the limitations when parsing large pi agent session JSONL files?▼

Parsing large pi agent session JSONL files requires sufficient memory to load the entire execution history. Complex sessions with many subagent runs may produce extensive outputs that complicate manual review.