[中文文档](README.md) | English

# pi-session-analyzer

[Source Code](https://github.com/catlain/pi-session-analyzer) | [npm](https://www.npmjs.com/package/pi-session-analyzer)

Session search and analysis for [pi](https://github.com/earendil-works/pi-coding-agent) — search historical sessions, reconstruct timelines, audit behavior, and generate takeover reports.

## Why You Need It

pi generates rich session logs (JSONL), but they're scattered across directories and hard to navigate. When you need to:

- Find what you did last week
- Continue work from a previous session
- Check who modified a file and why
- Audit an agent session for rule violations

...you'd have to manually dig through JSONL files. pi-session-analyzer gives the AI structured access to every session pi has ever run.

## How It Works

```
┌─── session_search ──────────────────────────────┐
│                                                  │
│  grep ──→ Full-text search across all sessions   │
│  file ──→ Find sessions that modified a file     │
│  list ──→ List recent N sessions                 │
│                                                  │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼ found sessionId
┌─── session_analyze ─────────────────────────────┐
│                                                  │
│  summary ──→ Metadata + abstract (start here)   │
│  entries ──→ Entry list (with grep + pagination) │
│  timeline ─→ Timeline (auto-labels [B1][B2] ...) │
│  chain ────→ Sub-agent call chain trace          │
│  audit ────→ Rule violation check                │
│  digest ───→ User/assistant conversation thread  │
│  branches ─→ Parallel branch analysis (/tree)    │
│  takeover ─→ 5-dimension handoff report          │
│  raw ──────→ Raw JSONL data                      │
│                                                  │
└──────────────────────────────────────────────────┘
```

## Installation

```bash
pi install git:github.com/catlain/pi-session-analyzer
```

> **Prerequisite**: [pi](https://github.com/earendil-works/pi-coding-agent) must be installed.

## Tools

### `session_search`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `action` | `"grep"` \| `"file"` \| `"list"` | ✅ | — | Search mode |
| `query` | string | grep/file | — | Keyword (grep) or file path (file) |
| `limit` | number | ❌ | `20` | Max results |
| `editOnly` | boolean | ❌ | `false` | grep mode: only search edit/write operations |

**Examples:**

```
session_search(action: "grep", query: "roadmap")
session_search(action: "file", query: "src/index.ts")
session_search(action: "list", limit: 10)
session_search(action: "grep", query: "error", editOnly: true)
```

### `session_analyze`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `sessionId` | string | ✅ | — | Session ID (supports prefix match) |
| `action` | enum | ✅ | — | See action table below |
| `limit` | number | ❌ | `20` | Max entries |
| `offset` | number | ❌ | — | Start position (0-based, entries mode) |
| `grep` | string | ❌ | — | Keyword filter (entries mode, supports regex) |

**Action reference:**

| Action | Output | Best for |
|--------|--------|----------|
| `summary` | Metadata + abstract | First look at a session |
| `entries` | Filtered entry list | Finding specific events |
| `timeline` | Chronological with branch labels | Understanding session flow |
| `chain` | Sub-agent call trace | Debugging sub-agent workflows |
| `audit` | Rule violations | Checking agent behavior |
| `digest` | User/assistant conversation | Reading what happened |
| `branches` | Per-branch analysis | Analyzing `/tree` forks |
| `takeover` | 5-dimension handoff report | Continuing from a past session |
| `raw` | Raw JSONL entries | Low-level debugging |

**Examples:**

```
session_analyze(sessionId: "abc123", action: "summary")
session_analyze(sessionId: "abc123", action: "entries", grep: "error|fail")
session_analyze(sessionId: "abc123", action: "takeover")
session_analyze(sessionId: "abc", action: "entries", offset: 0, limit: 10)  # pagination
```

## Storage

Session data is stored in pi's data directory:

| Data | Location |
|------|----------|
| Session JSONL files | `~/.local/share/pi-coding-agent/sessions/` |
| Per-session entries | `{sessionId}.jsonl` |
| Session ID matching | Prefix match — pass `abc` to match `abc123def...` |

## Use Cases

| Scenario | Workflow |
|----------|----------|
| **"What did I do last week?"** | `list` → `summary` → `digest` |
| **"Who changed this file?"** | `file(query: "path/to/file")` → `timeline` |
| **"Continue where I left off"** | `takeover` → get 5-dimension handoff (intent, files, steps, next steps, decisions) |
| **"Why did this break?"** | `entries(grep: "error")` → `audit` |
| **"What did the sub-agent do?"** | `chain` → trace sub-agent execution |

## Best Practices

### ✅ Recommended
- Always start with `summary` — it's fast and gives you the full picture before drilling in
- Use `grep` filter in `entries` mode to find specific events without loading everything
- Use prefix match for sessionId — no need to type the full ID
- For large sessions (>100 entries), use `offset` + `limit` for pagination instead of loading all at once
- Use `takeover` when switching machines or resuming work the next day

### ❌ Not Recommended
- Don't use `raw` for large sessions — use `entries` with pagination instead
- Don't confuse `session_search` actions (`grep`/`file`/`list`) with `session_analyze` actions — they're different tools
- Don't skip `summary` and go straight to `raw` — you'll waste context on irrelevant data

## Limitations

| Limitation | Detail |
|------------|--------|
| Read-only | Cannot modify session data, only analyze it |
| No real-time streaming | Analyzes completed sessions only |
| Prefix match ambiguity | Short prefixes may match multiple sessions |
| Audit rules are static | Custom audit rules require code changes |

## Architecture

```
pi-session-analyzer/
├── index.ts              # Entry: register session_search + session_analyze tools
├── core.ts               # Session resolution, JSONL reader, types
├── core-visible.ts       # Visible sub-agent file resolution
├── search.ts             # list + grep implementation
├── search-file.ts        # file search (find sessions editing specific files)
├── search-utils.ts       # Shared search helpers
├── analyze.ts            # summary/entries/timeline/chain/raw/branches
├── digest.ts             # User/assistant conversation extraction
├── audit.ts              # Rule violation checker
├── audit-rules.ts        # Audit rule definitions
├── audit-types.ts        # Audit-specific types
├── takeover.ts           # Takeover tool entry point
├── takeover-core.ts      # 5-dimension takeover report logic
├── tests/                # Unit tests
└── package.json
```

**Dependencies**:
- `@pi-atelier/shared-utils` (bundled) — `truncatedResult` for large outputs
- `@earendil-works/pi-coding-agent` — ExtensionAPI (peer)

## License

MIT