Documentation Index
Fetch the complete documentation index at: https://mintlify.com/earendil-works/pi/llms.txt
Use this file to discover all available pages before exploring further.
Pi saves every conversation as a session. Sessions are stored as JSONL files with a tree structure: each entry has an id and parentId, enabling in-place branching without creating new files. You can continue previous work, explore alternatives from earlier points, and recover from long sessions that approach context limits.
Session storage
Sessions auto-save to ~/.pi/agent/sessions/, organized by working directory. Use /session in interactive mode to see the current session file path, session ID, message count, token usage, and cost.
pi -c # Continue the 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 UUID
pi --fork <path|id> # Fork a session file or ID into a new session
Use /session to find the current session ID, then pass it to --session <id> or --fork <id> in a future invocation.
Session commands
The following commands are available in interactive mode:
| 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 |
/export [file] | Export the session to HTML |
/share | Upload as a private GitHub gist with a shareable HTML link |
Resuming and naming sessions
/resume opens a session picker for the current project. pi -r opens the same picker at startup.
In the picker you can:
- Search by typing
- Toggle path display with
Ctrl+P
- Toggle sort mode with
Ctrl+S
- Filter to named sessions with
Ctrl+N
- Rename with
Ctrl+R
- Delete with
Ctrl+D, then confirm
Use /name <name> to give a session a human-readable name. Named sessions are easier to identify in the picker.
/name Refactor auth module
Branching
Sessions use a tree structure. Every entry has an id and parentId, and the current position is the active leaf. You can navigate to any earlier point and continue from there — all branches are preserved in a single JSONL file.
├─ 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..."
/tree
/tree lets you jump to any previous point in the current session and continue from there, without creating a new file.
Tree controls:
| Key | Action |
|---|
↑ / ↓ | Navigate visible entries |
← / → | Page up or down |
Ctrl+← / Alt+← | Fold branch or jump to previous segment |
Ctrl+→ / Alt+→ | Unfold branch or jump to next segment |
Shift+L | Set or clear a label (bookmark) on the selected entry |
Shift+T | Toggle label timestamps |
Ctrl+O | Cycle filter mode |
Enter | Select the entry |
Escape / Ctrl+C | Cancel |
default, no-tools, user-only, labeled-only, all. Configure the default with treeFilterMode in settings.
Selection behavior:
- Selecting a user message places that message in the editor for editing and resubmission, creating a new branch.
- Selecting an assistant, tool, or compaction entry moves the leaf to that point, leaving the editor empty so you can continue from there.
When navigating away from a branch, Pi can summarize the work you are leaving behind and attach that summary at the new position. When prompted, choose no summary, summarize with the default prompt, or summarize with custom focus instructions.
/fork and /clone
/fork opens a selector of previous user messages on the active branch, copies the active path up to that point, and places the selected prompt in the editor for modification. The result is a new session file.
/clone duplicates the current active branch into a new session file at the current position. The new session keeps the full active-path history and opens with an empty editor.
pi --fork <path|id> forks an existing session file or partial session UUID directly from the CLI, copying the full source session into a new session file in the current project.
| 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 fresh from an earlier prompt | Duplicate current work before continuing |
Compaction
Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones, so the session remains usable.
Compaction is lossy. The full history remains in the JSONL file and can be revisited with /tree, but the summarized messages are not sent to the LLM verbatim.
Triggering compaction
Run /compact to compact the current context. Optionally pass custom instructions to focus the summary:/compact Focus on the database schema decisions
Auto-compaction is enabled by default. It triggers in two situations:
- Overflow recovery — when the context window is exceeded, Pi compacts and retries automatically.
- Proactive — when context approaches the limit (context tokens > context window minus
reserveTokens).
Compaction settings
Configure compaction in ~/.pi/agent/settings.json or .pi/settings.json:
{
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
| Setting | Default | Description |
|---|
compaction.enabled | true | Enable auto-compaction |
compaction.reserveTokens | 16384 | Tokens reserved for the LLM response |
compaction.keepRecentTokens | 20000 | Recent tokens to keep (not summarized) |
"enabled": false to disable auto-compaction. You can still compact manually with /compact.
You can customize compaction behavior using extensions. See the compaction internals in the source repository for the session_before_compact event hook.