Skills › Scientific Agent Skills › pi-agent › sessions.md

sessions.md

58 lines · skills/pi-agent/references/sessions.md at 5f2bc03

Open on GitHub

1# Sessions

3Source: https://pi.dev/docs/latest/sessions

5Reviewed against Pi 0.99.2 and the package versions listed in `../SKILL.md` on 2026-09-30.

7Pi auto-saves conversations to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL tree.

Sessions

Source: https://pi.dev/docs/latest/sessions

Reviewed against Pi 0.99.2 and the package versions listed in ../SKILL.md on 2026-09-30.

Pi auto-saves conversations to ~/.pi/agent/sessions/, organized by working directory. Each session is a JSONL tree.

Raw lines 1 to 8

9## Session Commands

11```bash

12pi -c # continue most recent

13pi -r # browse and select

14pi --no-session # ephemeral, do not save

15pi --name "my task" # display name at startup

16pi --session <path|id> # specific file or partial session ID

17pi --fork <path|id> # fork into a new session file

18```

20Interactive: `/resume`, `/new`, `/name <name>`, `/session` (file, ID, message count, tokens, cost), `/tree`, `/fork`, `/clone`, `/compact [prompt]`, `/export [file]`, `/share`.

Session Commands

pi -c                  # continue most recent
pi -r                  # browse and select
pi --no-session        # ephemeral, do not save
pi --name "my task"    # display name at startup
pi --session <path|id> # specific file or partial session ID
pi --fork <path|id>    # fork into a new session file

Interactive: /resume, /new, /name <name>, /session (file, ID, message count, tokens, cost), /tree, /fork, /clone, /compact [prompt], /export [file], /share.

Raw lines 9 to 21

22## Resuming and Deleting

24`/resume` (and `pi -r`) opens a picker for the current project. Search by typing; Ctrl+P toggles path display, Ctrl+S cycles sort mode, Ctrl+N filters to named sessions, Ctrl+R renames, Ctrl+D deletes with confirmation. Pi uses the `trash` CLI when available instead of permanently removing files.

Resuming and Deleting

/resume (and pi -r) opens a picker for the current project. Search by typing; Ctrl+P toggles path display, Ctrl+S cycles sort mode, Ctrl+N filters to named sessions, Ctrl+R renames, Ctrl+D deletes with confirmation. Pi uses the trash CLI when available instead of permanently removing files.

Raw lines 22 to 25

26## Branching with `/tree`

28Sessions are trees: every entry has `id` and `parentId`, and the current position is the active leaf. `/tree` jumps to any previous point and continues from there without creating a new file.

30| Key | Action |

31|---|---|

32| ↑/↓ | Navigate visible entries |

33| ←/→ | Page up/down |

34| Ctrl+←/→ or Alt+←/→ | Fold/unfold or jump between branch segments |

35| Shift+L | Set or clear a label on the selected entry |

36| Shift+T | Toggle label timestamps |

37| Enter | Select entry |

38| Escape / Ctrl+C | Cancel |

39| Ctrl+O | Cycle filter mode |

41Filter modes: default, no-tools, user-only, labeled-only, all. Set the default with `treeFilterMode`.

Branching with `/tree`

Sessions are trees: every entry has id and parentId, and the current position is the active leaf. /tree jumps to any previous point and continues from there without creating a new file.

Key	Action
↑/↓	Navigate visible entries
←/→	Page up/down
Ctrl+←/→ or 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: default, no-tools, user-only, labeled-only, all. Set the default with treeFilterMode.

Raw lines 26 to 42

43### Selection Behavior

45Selecting a **user or custom** message moves the leaf to that message's parent, puts the message text in the editor, and lets you edit and resubmit — creating a new branch. Selecting an **assistant, tool, compaction, or other non-user** entry moves the leaf there with an empty editor so you continue from that point. Selecting the root user message resets the leaf to an empty conversation with the original prompt in the editor.

Selection Behavior

Selecting a user or custom message moves the leaf to that message's parent, puts the message text in the editor, and lets you edit and resubmit — creating a new branch. Selecting an assistant, tool, compaction, or other non-user entry moves the leaf there with an empty editor so you continue from that point. Selecting the root user message resets the leaf to an empty conversation with the original prompt in the editor.

Raw lines 43 to 46

47## Tree vs Fork vs Clone

50|---|---|---|---|

Tree vs Fork vs Clone

	`/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

Raw lines 47 to 55

56## Branch Summaries

58When `/tree` switches away from one branch, Pi can summarize the abandoned branch and attach the summary at the new position, preserving context without replaying the branch. When prompted, choose no summary, the default prompt, or custom focus instructions. Internals and extension hooks: `references/compaction.md`. File format and `SessionManager` API: `references/session-format.md`.

Branch Summaries

When /tree switches away from one branch, Pi can summarize the abandoned branch and attach the summary at the new position, preserving context without replaying the branch. When prompted, choose no summary, the default prompt, or custom focus instructions. Internals and extension hooks: references/compaction.md. File format and SessionManager API: references/session-format.md.

Raw lines 56 to 58