Chapter 5 · Session Management: Resume and Branch

Chapter goals: Understand the storage structure and tree本质 of pi sessions; master the全套 operations for resume/name/fork/clone; safely "go back to the past" within the same session to尝试 different approaches.

5.1 Where Sessions Live

Sessions auto-save as JSONL files, archived by working directory:

~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl

<path> is the working directory path (/ replaced with -). Each JSONL file is not a linear log, but a message tree: each record带 id and parentId; the当前活跃位置 is the tree's leaf node — this is正是 the data structure基础 for "in-place branching" (开岔 without copying the file). The session format has迭代到 v3 (v1 linear structures auto-migrate on load).

# Quick-peek at a session file's content形态
head -3 ~/.pi/agent/sessions/--Users-you-demo--/*.jsonl | python3 -m json.tool 2>/dev/null | head -20

Each line is a JSON object带 type field: user/assistant messages, model switches, thinking level changes, labels, compaction summaries, branch summaries, extension entries — each a distinct entry type.

5.2 Four Postures for Resuming Sessions

pi -c                    # Continue the most recent session in the current directory
pi -r                    # Open the session picker at startup
pi --session <path|id>   # Directly指定 the session file path or partial UUID
pi --no-session          # Temp mode;本次对话不落盘

Interactive equivalents: /resume (picker), /new (new session). Use /session anytime to查看 the current session's file path, session ID, message count, tokens, and cost.

Management operations in the picker:

Key	Function
Type directly	Search sessions
Ctrl+P / Ctrl+S	Switch path display / sorting
Ctrl+N	Show only named sessions
Ctrl+R / Ctrl+D	Rename / delete (moves to trash when the trash CLI is installed)

5.3 Naming: Making History Searchable

pi --name "Refactor auth module"        # Name at startup (-n is equivalent)

/name Refactor auth module      # Rename mid-session

Named sessions are更容易 found in /resume and pi -r;配合 Ctrl+N filtering to快速定位 long-running tasks. For team collaboration场景建议约定命名规范 (e.g. ticket-id-short-desc).

5.4 Branching: Trying Different Approaches on the Same Tree

This is pi's会话系统 most valuable capability. Typical scenario: ask the agent to改 a complex logic段; the result is unsatisfactory — no need to undo and重来; just fork.

/tree — In-place navigation of the entire session tree

├─ user: "Help me optimize this function"
│  └─ assistant: "Approach A: cache the计算结果..."
│     ├─ user: "Try approach B..."        ← switch to this line to继续 from here
│     └─ user: "Actually rollback to A and optimize..."

• Double-tap Escape or /tree to open; ↑/↓ to navigate; Ctrl+←/→ to fold/expand or跨分支跳转;
• Shift+L to tag an entry with a bookmark label; Shift+T to显示 the label timestamp;
• Ctrl+O to循环过滤模式: default → no-tools → user-only → labeled-only → all (default可 set via the treeFilterMode setting);
• Selecting a user message: move the cursor to its parent node;put the message back into the editor for modification and重发 → form a新分支; selecting a non-user entry (e.g. assistant)则直接从那里继续.

/fork and /clone — Spawn new session files

Feature	/tree	/fork	/clone
Output	Same session file	New session file	New session file
Perspective	Complete tree	User message picker	Current active branch
Typical use	In-place探索 multiple approaches	Start fresh from an early prompt	Backup current progress before continuing

The CLI also has对应入口: pi --fork <path|id> forks an existing session into a new file.

Context Loss and Remediation When Switching Branches

When /tree switches away from a branch, the离开分支's details are no longer in the活跃 context. pi提供 branch summary: when prompted you can选 "no summary / default summary / custom focus";浓缩 the旧分支的关键信息 and attach it to the新位置.

5.5 Session Organization Habit Suggestions

1. One task one session; --name at启动 to avoid巨型混合 sessions blowing up context (compression机制 see Chapter 6);
2. /clone a copy before大改动;相当于给对话现场做快照;
3. Tag关键决策 points with Shift+L;快速复盘后 with the labeled-only filter mode; 4.定期清理废弃实验 sessions under ~/.pi/agent/sessions/ (or Ctrl+D走 the trash in /resume);
4. For sharing/archiving use /export (HTML/JSONL file) or /share (private GitHub gist link).

Chapter Summary

• Sessions are JSONL tree files under ~/.pi/agent/sessions/--<path>--/; id/parentId构成 branching能力的基础;
• Resume四件套: -c recent session, -r picker, --session <path|id>定点恢复, --no-session不留痕;
• /tree in-place branching + labels + filtering is方案探索利器; /fork, /clone for拆出新文件;
• Switching branches丢 context;补 with branch summary;
• Naming + clone snapshots + label复盘 are三条实用整理纪律.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the底层结构 of a pi session file?

2. To "in-place explore multiple solutions to the same problem and留 them in the same session", which should优先使用?

3. Pressing Ctrl+D in the /resume picker does what?

4. Regarding context when switching branches with /tree, which statement is correct?

🛠️ Hands-on Practice

1. Find a历史 session and execute /tree; switch to three steps back to re-ask a question; observe新分支的生成 and原分支的保留.
2. Use /name to rename the最近 three sessions for the current project per the "date-topic"规范; verify效果 with Ctrl+N filtering.
3. For a failed修改尝试 use /tree's branch summary功能 (custom focus);对比有无摘要时后续对话的质量差异.

Proceed to Chapter 6: Context Compaction and Context Files to学会驯服无限增长的上下文.