📖 pi-atelier 实战指南 — 从零教会你使用 pi-atelier 扩展生态，包含完整示例和最佳实践。

English | 程序中文文档

pi-journal

源码仓库 | npm

Session journaling extension for pi — automatic session logging, entry indexing, and timeline reconstruction.

Why You Need It

AI coding sessions generate valuable history — decisions made, code changed, errors fixed. But pi's native session files are raw JSONL, hard to read and search. pi-journal turns sessions into structured, searchable journals you can actually use.

Use it when: You want to review past sessions, track decisions, find recurring errors, or share session history with your team.

How It Works

Session Start → Create journal file
        │
        ▼ during session
Tool calls, edits, decisions, errors
        │
        ▼ each event
Journal entry logged (timestamp + type + summary + files)
        │
        ▼ session end
Finalize journal with summary
        │
        ▼
<project>/.pi/journal/<date>-<session-id>.json

Journal files are stored in <project>/.pi/journal/ or ~/.pi/agent/journal/ (global).

Installation

pi install git:github.com/catlain/pi-journal

Journal Format

Each journal entry includes:

| Field | Description | |-------|-------------| | Timestamp | When the event occurred | | Type | edit, command, decision, error, tool_call | | Summary | Human-readable description | | Files | List of affected file paths | | Details | Additional context (error messages, command output, etc.) |

Use Cases

| Scenario | What You Get | |----------|-------------| | Session retrospective | Read a session's journal to see everything accomplished | | Decision log | Track why certain technical decisions were made | | Error patterns | Find recurring errors across sessions | | Audit trail | See exactly what changes were made and when | | Knowledge transfer | Share session journals with team members |

Best Practices

✅ Recommended

• Commit .pi/journal/ to git — it's valuable project history
• Review journals after long sessions to catch things you missed
• Use journal type filters to find specific kinds of events
• Pair with pi-session-analyzer for deeper session insights

❌ Not Recommended

• Don't store sensitive data in journal summaries
• Don't manually edit journal files — they're auto-generated
• Don't disable journaling for important projects

Limitations

| Limitation | Detail | |------------|--------| | JSONL-based storage | Not a database — search is linear scan | | No real-time streaming | Entries are flushed periodically, not per-event | | Storage growth | Journal files accumulate; consider periodic cleanup | | No cross-project view | Each project has its own journal directory |

Architecture

pi-journal/
├── index.ts       # Entry: register session hooks
├── writer.ts      # Journal file write + flush
├── entry.ts       # Entry type definitions + construction
├── reader.ts      # Journal search + filtering
└── package.json

Dependencies:

• @earendil-works/pi-coding-agent — ExtensionAPI (peer)

License

MIT