packages/coding-agent/docs/sessions.md
Pi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
Sessions auto-save to ~/.pi/agent/sessions/, organized by working directory. Each session is a JSONL file with a tree structure.
pi -c # Continue most recent session
pi -r # Browse and select from past sessions
pi --no-session # Ephemeral mode; do not save
pi --session <path|id> # Use a specific session file or partial session ID
pi --fork <path|id> # Fork a session file or partial session ID into a new session
Use /session in interactive mode to see the current session file, session ID, message count, tokens, and cost.
For the JSONL file format and SessionManager API, see Session Format.
| Command | Description |
|---|---|
/resume | Browse and select previous sessions |
/new | Start a new session |
/name <name> | Set the current session display name |
/session | Show session info |
/tree | Navigate the current session tree |
/fork | Create a new session from a previous user message |
/clone | Duplicate the current active branch into a new session |
/compact [prompt] | Summarize older context; see Compaction |
/export [file] | Export session to HTML |
/share | Upload as private GitHub gist with shareable HTML link |
/resume opens an interactive session picker for the current project. pi -r opens the same picker at startup.
In the picker you can:
When available, pi uses the trash CLI for deletion instead of permanently removing files.
Use /name <name> to set a human-readable session name:
/name Refactor auth module
Named sessions are easier to find in /resume and pi -r.
/treeSessions are stored as trees. Every entry has an id and parentId, and the current position is the active leaf. /tree lets you jump to any previous point and continue from there without creating a new file.
Example shape:
├─ user: "Hello, can you help..."
│ └─ assistant: "Of course! I can..."
│ ├─ user: "Let's try approach A..."
│ │ └─ assistant: "For approach A..."
│ │ └─ user: "That worked..." ← active
│ └─ user: "Actually, approach B..."
│ └─ assistant: "For approach B..."
| Key | Action |
|---|---|
| ↑/↓ | Navigate visible entries |
| ←/→ | Page up/down |
| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
| Shift+L | Set or clear a label on the selected entry |
| Shift+T | Toggle label timestamps |
| Enter | Select entry |
| Escape/Ctrl+C | Cancel |
| Ctrl+O | Cycle filter mode |
Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with treeFilterMode in Settings.
Selecting a user or custom message:
Selecting an assistant, tool, compaction, or other non-user entry:
Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
/tree, /fork, and /clone| Feature | /tree | /fork | /clone |
|---|---|---|---|
| Output | Same session file | New session file | New session file |
| View | Full tree | User-message selector | Current active branch |
| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
| Summary | Optional branch summary | None | None |
Use /tree when you want to keep alternatives together. Use /fork or /clone when you want a separate session file.
When /tree switches away from one branch to another, pi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
When prompted, choose one of:
See Compaction for branch summarization internals and extension hooks.
Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
For parsers, extensions, SDK usage, and the full SessionManager API, see Session Format.