Sessions, Trees & the TUI

Lesson 2: Sessions, Trees & the TUI

Pi treats every conversation as a session: a JSONL file with a tree structure, auto-saved to ~/.pi/agent/sessions/ and organized by working directory. Because sessions are trees, you can jump back to any earlier turn and branch from there — like git for your conversation.

Session commands and flags

pi -c                      # continue the most recent session
pi -r                      # browse and pick a past session
pi --no-session            # ephemeral: do not save anything
pi --name "Refactor auth"  # human-readable session name
pi --session <path|id>      # resume a specific session
pi --fork <path|id>        # fork a session into a new one

Inside the TUI, the big ones are /tree (navigate the session tree), /fork (new session from a previous user message), /clone (duplicate the current branch), /resume (picker), /new, /session (show file, ID, message count, tokens, and cost), /export (HTML/JSONL), /import, and /share (private GitHub gist with a shareable HTML link).

Editor features that save you (and the model) time

@ — fuzzy-search project files to reference
Tab — path completion
Shift+Enter — multi-line input
!command — run a shell command and send its output to the model
!!command — run a shell command without sending output to the model
Ctrl+X — copy the last assistant message
Ctrl+G — open an external editor (e.g. code --wait)
Ctrl+V — paste images directly into the terminal

The message queue

You don't have to wait for the agent to finish: Enter queues a steering message (delivered after the current tool calls), Alt+Enter queues a follow-up (delivered after all work completes), Escape aborts and restores queued messages, and Alt+Up pulls them back. Delivery order is configurable via steeringMode and followUpMode settings.

🪙 Token angle:

/session shows tokens and cost for the current session — check it before committing to a long task.
!!command is a quiet token win: run setup/verification commands without dumping their output into context.
--no-session is perfect for one-off questions you'll never resume — nothing saved, nothing to compact later.
/fork or /clone lets you explore an alternative path in a fresh context instead of dragging exploratory turns through the main session.

📺 Watch:

Learn 90% Of Pi Agent in Under 17 Minutes — Brandon Melville — a fast hands-on tour of the TUI, sessions, and daily workflow.

🧠 Knowledge Check

1. What shape do pi sessions have on disk?

2. Which command runs a shell command WITHOUT sending its output to the model?

3. How can you see the token count and cost of the current session?