session-reader

Parse Pi agent session JSONL files into readable conversation histories and diagnostic reports.

2|Updated May 5, 2026
One-click install
npx skills add https://github.com/OrestesK/pi --skill session-reader-orestesk
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: session-reader
Source: https://github.com/OrestesK/pi/tree/main/skills/session-reader
Command: npx skills add https://github.com/OrestesK/pi --skill session-reader-orestesk

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill transforms dense Pi agent session JSONL files into readable, navigable conversation histories, making it easier to understand what happened, diagnose failures, and review agent activity.

Core Features & Use Cases

  • Session Discovery: Locates recent session files using configured Pi session directories and project paths.
  • Flexible Analysis Modes: Provides conversation, table of contents, overview, detailed turn, issues, tools, costs, subagents, and full-session views.
  • Targeted Investigation: Supports turn ranges, keyword search, content truncation, error detection, retry analysis, tool inspection, and subagent drill-down.
  • Use Case: When an agent produces an unexpected result, use the table of contents to find the relevant exchange, inspect the detailed turn, and review tool errors or subagent activity.

Quick Start

Use the session-reader skill to analyze the attached Pi session JSONL file and summarize what happened, including any errors and tool usage.

Frequently Asked Questions about session-reader

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

FAQPage Schema
How do I parse Pi agent session JSONL files into readable conversation histories?

You can parse Pi agent session JSONL files into readable conversation histories by running the session-reader script, which transforms dense logs into navigable text and diagnostic reports.

What is the best way to debug unexpected Pi agent results and inspect tool call errors?

The best way to debug unexpected Pi agent results is to generate a table of contents from the session JSONL, locate the relevant exchange, and inspect the detailed turn for tool call errors or subagent activity.

Can I analyze token cost and subagent activity within Pi session JSONL logs?

Yes, you can analyze token cost and subagent activity by applying the dedicated cost analysis and subagent investigation modes to the Pi session JSONL file.

Does parsing Pi session JSONL files require any external dependencies or specific Python versions?

Parsing Pi session JSONL files requires Python 3.12 or newer and uses only standard-library dependencies, meaning no external packages or installations are needed.

What analysis modes are available for reviewing Pi agent session JSONL data?

Available analysis modes for Pi agent session JSONL data include conversation, table of contents, overview, detailed turn, issues, tools, costs, subagents, and full-session views.

How do I search for specific keywords or truncate content when debugging a Pi session JSONL file?

You can search for specific keywords or truncate content during debugging by applying targeted investigation parameters, which support keyword search, content truncation, turn ranges, and error detection.