11  Sessions

11.1 Session Storage

Pi saves conversations as JSONL session files in ~/.pi/agent/sessions/, organized by working directory. Each session is a tree-structured file containing all messages, tool calls, tool results, and metadata.

11.1.1 Directory Structure

~/.pi/agent/sessions/
├── Users-wuzhiguo-projects-app/
│   ├── 550e8400-e29b-41d4-a716-446655440000.jsonl
│   ├── 6ba7b810-9dad-11d1-80b4-00c04fd430c8.jsonl
│   └── session-name.jsonl
└── Users-wuzhiguo-projects-other/
    └── ...

Session file names are based on a UUID or a custom name. The working directory path is encoded in the parent directory name (with / replaced by -).

11.1.2 Session Lifecycle

graph TD
    A[Start Pi] --> B{Continue/Resume?}
    B -->|Yes| C[Load existing session]
    B -->|No| D[Create new session]
    C --> E[Interactive session]
    D --> E
    E --> F[Auto-save on each message]
    F --> G{User exits}
    G --> H[Session persisted]

11.2 Session Commands

11.2.1 Resuming Sessions

# Continue the most recent session in this directory
pi -c
pi --continue

# Browse and select a session interactively
pi -r
pi --resume

# Open a specific session by file path or partial UUID
pi --session /path/to/session.jsonl
pi --session 550e8400

# Fork a session into a new session file
pi --fork /path/to/session.jsonl
pi --fork 550e8400

11.2.2 In-Session Commands

Command Description
/session Show session file, ID, message count, tokens used, and cost
/new Start a new session
/resume Browse and select a previous session to resume
/name <name> Set the session display name
/tree Open the session tree navigator
/fork Create a new session from a previous user message
/clone Duplicate the current active branch into a new session file
/compact [prompt] Compact context to free space
/export [file] Export session to HTML or JSONL
/import <file> Import and resume a session from JSONL
/share Upload as private GitHub gist with shareable HTML link

11.2.3 Deleting Sessions

# Delete from disk
rm ~/.pi/agent/sessions/<dir>/<file>.jsonl

# Or use the file manager
# Sessions are plain JSONL files and can be managed with standard tools
Warning

Deleting session files is permanent. There is no trash or recycle bin. Consider exporting important sessions before deleting.

11.3 Session Naming

11.3.1 Setting a Name

# At startup
pi --name "refactor auth module"
pi -n "debug test failures"

# During a session
/name refactor auth module

11.3.2 Name Display

The session name appears in:

  • The footer status bar
  • The /resume session browser
  • Session metadata in the JSONL file
  • Exported HTML files

11.4 The /tree Command

The session tree is one of Pi’s most powerful features. Because sessions are stored as trees rather than linear lists, you can navigate to any point in the conversation and continue from there.

11.4.1 How the Tree Works

graph TD
    A[User: Help me debug] --> B[Assistant: Let me look...]
    B --> C[Tool: read file.ts]
    C --> D[Assistant: I found issue A]
    D --> E1[User: Fix issue A]
    D --> E2[User: What about issue B?]
    E2 --> F[Assistant: Let me check...]
    F --> G[User: Fix issue B]
    E1 --> H[Assistant: Fixed A]

Each user message starts a new branch. When you navigate to an earlier point and type a new message, Pi creates a new branch from that point.

11.4.2 Tree Controls

Key Action Description
↑ / ↓ Navigate Move up/down through messages
← / → Expand/Collapse Collapse or expand branch children
Enter Select Navigate to the selected message and continue from there
/fork Fork Create a new session file from the selected message
/clone Clone Duplicate the current active branch
Escape Exit Return to the editor without navigating

11.4.3 Tree View

The tree view shows:

  • Each message with its type (user, assistant, tool call, tool result)
  • Branch structure with visual indentation
  • Active branch highlighted
  • Message labels (custom labels set with /label)
  • Abandoned branch summaries (when branch summary is enabled)

11.5 /tree vs /fork vs /clone

Feature /tree /fork /clone
What it does Navigate within the current session Create a new session from an earlier point Duplicate current branch to new session
Modifies current file Yes (changes active branch) No (creates new file) No (creates new file)
Starting point Any message in tree Selected or specified message Current active branch
New session file No Yes Yes
Use case Explore alternatives Start fresh from earlier point Backup current work

11.5.1 When to Use Each

  • /tree: You want to explore a different direction within the same session file
  • /fork: You want to create a separate session that branches from an earlier point
  • clone: You want to preserve the current state before making significant changes

11.6 Branch Summaries

When branch summary is enabled in settings, Pi automatically summarizes branches that were explored but not continued. This helps you understand the session tree at a glance without reading every message in abandoned branches.

11.6.1 Enabling Branch Summaries

// ~/.pi/agent/settings.json
{
  "branchSummary": true
}

11.6.2 What Gets Summarized

A branch is eligible for summarization when:

  • It has more than a minimum number of messages
  • It was not the last active branch (i.e., the user navigated away)
  • It has not already been summarized

See the Compaction & Branch Summarization chapter for technical details.

11.7 Exporting Sessions

11.7.1 HTML Export

/export ~/session.html

Produces a standalone HTML file with:

  • Full conversation rendered with syntax highlighting
  • Tool calls and results in formatted blocks
  • Session metadata (model, tokens, cost)
  • Branch structure visible

11.7.2 JSONL Export

/export ~/session.jsonl

Produces a copy of the session JSONL file, useful for:

  • Backup
  • Sharing with other Pi users
  • Importing on another machine

11.7.3 GitHub Gist

/share

Uploads the session as a private GitHub gist with a shareable HTML link. Requires GitHub authentication.

11.8 Session Format Overview

Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object representing an entry in the session tree. The format supports:

  • Tree structure (parent/child relationships)
  • Multiple entry types (messages, tool calls, tool results, compactions)
  • Metadata (timestamps, model info, token usage)
  • Custom entry types from extensions

For the complete format specification, see the Session File Format chapter.

Tip

Sessions are plain JSONL files. You can inspect them with jq, grep through them, or process them with any tool that handles line-delimited JSON.