Pi School
← All lessons

Lesson 8

Sessions

Manage and resume conversations with Sessions.

Every conversation you have with Pi is a session. Sessions have their own history and context — the model remembers everything said within a session, but starts fresh in a new one. A single project can have as many sessions as you like.

Where sessions live

Sessions auto-save to ~/.pi/agent/sessions/, organized by working directory. Each one is a JSONL file with a tree structure — more on the tree part in the next lesson.

Starting a new session

Type /new in the prompt to start fresh. The current session stays in your history; you can always come back to it.

Naming and resuming sessions

Give a session a name so it’s easier to find later:

/name Refactor auth module

Or set it at startup:

pi --name "Refactor auth module"

To pick up a past session:

  • /resume — opens an interactive picker of past sessions for the current project.
  • pi -r — opens the same picker, but at startup from your terminal.
  • pi -c — skips the picker and continues your most recent session directly.

Type /session any time to see info about your current session: file path, session ID, message count, tokens used, and cost.

Saving and sharing a session

Two different commands, for two different needs:

  • /export [file] — writes the session to HTML or JSONL, saved locally. No account needed. Good for keeping a record or reviewing a session outside the terminal.
  • /share — uploads the session and gives you a viewer link. By default it uses a private GitHub gist, which needs GitHub authentication. We haven’t set that up yet; you’ll get to the full git/GitHub setup in the “Use Git and GitHub” exercise later in the course. (If you’ve signed in to Radius, Earendil’s own service, with /login radius, /share uses that instead.) For now, just know the command exists.

Review a session before sharing it: it can contain file contents, command output, and anything else that came up in the conversation.

If Pi itself misbehaves, /bug prepares a private bug report for the Pi developers. You choose whether to include the transcript.

Exercise: read your own session file

Session files aren’t locked behind a special export command — they’re just JSONL, readable directly.