Pi Session Tree Browser

A browser UI for inspecting and continuing Pi session fork trees.

Pi already supports saved sessions and forks, but long forked conversations are hard to inspect from a terminal alone. This package adds a local browser viewer that turns a Pi session family into a navigable tree, renders the transcript, and lets you continue selected branches from the web.

Why This Exists

Pi's session model is powerful: you can fork from earlier points, resume old sessions, compact long conversations, and keep multiple branches around. The missing piece is a visual workspace for understanding that history.

Pi Session Tree Browser is built for workflows where you repeatedly branch, compare, prune, and continue conversations:

• research sessions with many alternative directions
• coding sessions where one assistant answer becomes several experiments
• long exploratory chats where old context should remain inspectable
• fork-heavy workflows where the terminal view is no longer enough

Features

Session Tree Navigation

The left sidebar shows the current session and its forked descendants as a tree. User and assistant messages are listed in order, and fork labels are inserted at the branch point so you can see where each branch came from.

Clicking a sidebar item jumps the transcript to the corresponding message. Sidebar filters let you show or hide user messages, assistant messages, thinking blocks, and tool blocks.

Transcript Viewer

The main pane renders the selected branch as a readable transcript. It supports:

• Markdown rendering
• thinking block toggles
• tool block toggles
• links and code blocks
• long conversations with independent scrolling

The layout is modeled after Pi's exported HTML sessions, but stays connected to live session state.

Fork From Assistant Messages

Right-click an assistant message in the sidebar and create a fork from that point. You can give the fork a display name, which appears directly in the tree.

This matches the practical Pi workflow: fork after a complete assistant response, then continue a new direction without rewriting the original branch.

Browser Composer

The bottom composer can send a normal user message to the selected session. If the session does not already have an active runtime, the viewer starts a Pi RPC runtime for that session.

Assistant output streams into the browser while the runtime is working, so the browser can become the active interaction surface after /session-tree-browser exits the terminal.

Branch Management

The viewer includes local cleanup tools for long-running trees:

• delete a fork branch
• delete all messages after a selected message
• collapse old sidebar ranges into compact blocks
• reload the full session view when needed

Deletion rewrites local Pi session JSONL files. It is designed for personal local session management, not collaborative multi-user editing.

Runtime Management

The viewer can manage multiple background Pi runtimes for different sessions in the same tree. Runtimes are capped and idle runtimes are cleaned up automatically.

Current defaults:

• maximum background runtimes: 10
• idle runtime cleanup: 10 minutes
• standalone viewer shutdown when inactive: 30 minutes

Install

From npm:

pi install pi-session-tree-browser

The npm package name is reserved for the intended public release. Until it is published to npm, install from GitHub:

From GitHub:

pi install https://github.com/cookerpapa/pi-session-tree-browser

From a local checkout:

pi install .

Usage

Run Pi normally in a directory where you want to work:

pi

Send at least one message so Pi creates a persisted session. Then run:

/session-tree-browser

The command starts a local viewer server, prints a browser URL, and exits the current Pi CLI. Open the printed URL to use the browser interface.

The viewer is designed for persisted Pi sessions. Do not start Pi with --no-session if you want to use this package.

Typical Workflow

1. Start a normal Pi session.
2. Talk to Pi until you have a useful assistant response.
3. Run /session-tree-browser.
4. Open the viewer URL.
5. Right-click an assistant message in the sidebar and fork from it.
6. Select the forked session.
7. Continue that branch from the web composer.
8. Delete or prune branches that are no longer useful.

Command

/session-tree-browser

Opens the browser viewer for the current persisted session tree.

Slash Commands In The Web Composer

The web composer sends normal user messages. It intentionally does not expose Pi's full slash-command surface. Slash commands are blocked unless this package explicitly allows them.

This keeps browser input predictable and avoids accidentally invoking unrelated Pi CLI commands from a web page.

Data Model

The viewer reads Pi's local session JSONL files and reconstructs the fork tree from session metadata. It does not upload session content anywhere.

When the browser sends a message, the viewer starts or reuses a local Pi RPC runtime for the selected session. The resulting messages are written by Pi itself into the normal session files.

When you delete or truncate branches, the viewer modifies local session files directly.

Limitations

• The viewer is local-only and intended for personal use.
• It does not provide authentication.
• It does not implement a sandbox.
• It does not sync state across machines.
• It is not a replacement for Pi's terminal UI; it is a visual workspace for session trees.
• Some Pi CLI-only interactions may not be available from the browser composer.

Safety

Pi does not provide a built-in sandbox or permission popup system. This package follows Pi's default model: the viewer and spawned Pi runtimes run with the same user-level permissions as the process that launched them.

Review third-party Pi packages before installing them.

Development

Clone the repo and install it into Pi from the package root:

git clone https://github.com/cookerpapa/pi-session-tree-browser
cd pi-session-tree-browser
pi install .

Then start Pi in any working directory and run:

/session-tree-browser

Status

This is an early package. The UI is optimized for local development workflows and may change between minor versions.