pi-insights

Session analytics and AI-powered insights for Pi — understand your AI coding workflow, identify friction, and continuously tailor your agent experience.

Background

Inspired by Claude Code's insights feature. Discovering patterns and shortcomings across past sessions, then using those findings to iteratively refine the agent experience, is incredibly powerful. Since Pi coding agent offers virtually unlimited customization potential — skills, extensions, hooks, AGENTS.md — this kind of self-aware feedback loop matters even more here. pi-insights closes that loop.

Quick Start

pi install npm:pi-insights

Then use /insights in any Pi session to view your session overview.

Commands

Command	Description
/insights [days|all]	Recent session overview in TUI (default: 30 days; press r for full HTML report)
/insights:session	Analyze the current session in TUI (press r for HTML report)
/insights:report [--session | --history [days|all]]	Generate a full HTML report directly
/insights:clear-cache	Clear cached AI facet analysis results

Features

Session Analytics

• Usage statistics — messages, tool calls, files modified, token usage, git activity
• Interaction timing — user response latency and assistant response time distributions
• Error breakdown — categorized tool errors (permission denied, file not found, syntax errors, etc.)
• Activity heatmap — GitHub-style daily session activity visualization
• Token usage trends — input/output token consumption over time
• Response time analysis — distribution buckets and hourly usage patterns

AI-Powered Analysis

• Session facets — LLM-generated analysis per session (goal, outcome, satisfaction, friction, session type)
• Personalized insights — interaction style, what works, friction points, actionable suggestions
• AGENTS.md recommendations — tailored suggestions for improving your agent configuration
• Ecosystem suggestions — skills, extensions, and hooks worth creating based on your workflow

Reports

• TUI dashboard — interactive terminal overview with key metrics
• HTML export — shareable reports with embedded charts and detailed analysis

How It Works

Session Logs (.jsonl)
        │
        ▼
   ┌─────────┐     ┌──────────────┐
   │ Parser   │────▶│  Statistics  │
   │ (utils)  │     │  (stats)     │
   └─────────┘     └──────┬───────┘
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
         ┌────────┐  ┌────────┐  ┌──────────┐
         │Heatmap │  │Charts  │  │Facets    │
         │        │  │        │  │(analysis)│
         └───┬────┘  └───┬────┘  └────┬─────┘
             │           │            │
             ▼           ▼            ▼
         ┌────────────────────────────────┐
         │      Report Generator          │
         │   (TUI + HTML output)          │
         └────────────────────────────────┘

1. Parse — reads Pi session .jsonl logs, extracts metadata (tokens, tools, files, timing)
2. Compute — aggregates statistics across sessions (totals, trends, distributions)
3. Analyze — sends per-session context to an LLM for facet extraction (cached to avoid redundant calls)
4. Report — generates an interactive TUI dashboard and/or exportable HTML report

Requirements

• Pi coding agent
• A configured model with API key (required for AI-powered facet analysis)

⚠️ Beta

This project is in early beta — the analysis methodology, report format, and caching strategy are still evolving. Treat generated insights as directional rather than authoritative, and watch your token usage: AI facet analysis makes LLM calls per session and can consume significant credits on large histories.

Development

# Clone and link locally
git clone https://github.com/RimuruW/pi-insights.git
cd pi-insights
pi install ./pi-insights

# Run tests
npm test

License

MIT