pi-session-anchor

Drop an anchor in your conversation tree — pi will return to that spot after a restart.

What it does

When you use /tree or /rewind to navigate to an earlier point in your session, pi-session-anchor saves that position (leafId) to a small sidecar file.

The next time you start pi (or resume the session), it restores the tree position so you pick up exactly where you left off — not at the latest message.

This fills the gap left by pi-rewind (which saves file state but not conversation tree position) and pi-undo-redo (which only incidentally saves position as a side-effect of its redo stack).

Resume switching

When you use /resume to switch between sessions, the anchor is also saved on session_shutdown. This ensures that switching away from and back to a session preserves the tree position correctly.

How it works

/tree → navigate to older message
  │
  ├─► pi-session-anchor saves newLeafId → sidecar
  │
  ▼ restart pi
  │
  ├─► session_start fires
  ├─► pi-session-anchor reads sidecar
  ├─► branch(savedLeafId) → in-memory leaf pointer restored
  └─► conversation tree shows the anchored position

No session entries are modified. The anchor is kept in ~/.pi/agent/state/session-anchor/<sessionId>.json — clean, separable, inspectable.

Commands

Command	Description
/pin	Manually save the current tree position as an anchor
/anchor	Show the saved anchor for the current session

The anchor is also auto-saved:

• On every /tree or /rewind navigation
• On session_shutdown (covers /resume switching, /reload, and normal quit)

Edge cases handled

Situation	Behaviour
Target entry compacted away	Silent fallback to latest position
Navigation to root (before first message)	Saved as leafId: null, restored via resetLeaf()
Sidecar file deleted / corrupted	Treated as "no anchor", normal startup
Multiple sessions	Separate sidecar per session ID
Anchor then continue chatting	New messages are children of the anchored position; anchor stays until next /tree overwrites it
/resume switch away and back	session_shutdown saves leafId before tear-down; session_start restores it on return

Installation

# If published on npm:
pi install pi-session-anchor

# Or copy to extensions directory:
cp -r pi-session-anchor ~/.pi/agent/extensions/

Then reload pi or restart.

Configuration (optional)

No configuration is required. If you want to disable auto-restore, remove the sidecar file for that session from ~/.pi/agent/state/session-anchor/.