Sessions #

Prime Agent saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.

Session Storage #

Sessions auto-save to ~/.prime/agent/sessions/. Each session is a JSONL file with a tree structure.

prime-agent --continue          # Continue the most recent session
prime-agent --resume [path|id]  # Browse past sessions or resume one directly
prime-agent --no-session        # Ephemeral mode; do not save
prime-agent --fork <path|id>    # Fork a session file or partial session ID into a new session

Use /session in interactive mode to see the current session file, session ID, and message count. Use /usage for token, cost, and context usage.

For the JSONL file format and SessionManager API, see Session Format.

Session Commands #

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
/usage	Show token, cost, and context usage
/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; see Compaction
/export [file]	Export session to HTML
/share	Upload as private GitHub gist with shareable HTML link

Resuming and Deleting Sessions #

/resume opens an interactive session picker for the current project. prime-agent --resume opens the same picker at startup, and prime-agent --resume <path|id> resumes a specific session.

A session records the directory it started in, and resuming runs it there: a session saved by another project continues in that project's directory, not in whichever directory you type the command from. To continue that same history in the current project instead, fork it with prime-agent --fork <id>.

An invalid ID exits with the closest unambiguous session ID when one is available. To open the picker and send an initial prompt after selecting a session, separate the prompt with --: prime-agent --resume -- "continue this work".

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

When available, Prime Agent uses the trash CLI for deletion instead of permanently removing files.

Naming Sessions #

Use /name <name> to set a human-readable session name:

/name Refactor auth module

Named sessions are easier to find in /resume and prime-agent --resume.

Branching with /tree #

Sessions are stored as trees. Every entry has an id and parentId, and the current position is the active leaf. /tree lets you jump to any previous point and continue from there without creating a new file.

Example shape:

├─ 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 Controls #

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

Selection Behavior #

Selecting a user or custom message:

1. Moves the leaf to the selected message's parent.
2. Places the selected message text in the editor.
3. Lets you edit and resubmit, creating a new branch.

Selecting an assistant, tool, compaction, or other non-user entry:

1. Moves the leaf to that entry.
2. Leaves the editor empty.
3. Lets you continue from that point.

Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.

/tree, /fork, and /clone #

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 a new session from an earlier prompt	Duplicate current work before continuing
Summary	Optional branch summary	None	None

Use /tree when you want to keep alternatives together. Use /fork or /clone when you want a separate session file.

Branch Summaries #

When /tree switches away from one branch to another, Prime Agent can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.

When prompted, choose one of:

1. no summary
2. summarize with the default prompt
3. summarize with custom focus instructions

See Compaction for branch summarization internals and extension hooks.

Session Format #

Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.

For parsers, extensions, SDK usage, and the full SessionManager API, see Session Format.