pi-session-snapshot

Save and restore the active path of a given Pi session.

Like this extension? See my other Pi extensions.

Useful for establishing a checkpoint from which you want to resume one or more sessions, such as when you have a fleet of worker agents who you don't want to onboard before each task.

A session snapshot preserves Pi conversation context only. It does not preserve Git history, files, uncommitted changes, environment variables, or processes.

Installation

From GitHub

pi install git:github.com/arcanemachine/pi-session-snapshot

From npm

pi install npm:@arcanemachine/pi-session-snapshot

From local clone

pi install /path/to/pi-session-snapshot

Or load the source entrypoint directly during development:

pi -e /path/to/pi-session-snapshot/src/index.ts

Commands

/snapshot
/snapshot save [name] [--force]
/snapshot load [name]
/snapshot list
/snapshot delete [name] [--force]

Running /snapshot opens a menu for saving, loading, deleting, and listing snapshots. Saving an existing name opens a safe-default confirm: No / Yes — answering No returns to the name field with the entered value intact (so you can save it under a different name), and Yes overwrites.

The top-level actions (save, load, list, delete) are autocompleted after /snapshot . /snapshot list prints the directory where snapshots are stored along with the saved snapshots.

For automation or non-TUI use, --force is required to replace or delete:

/snapshot save baseline --force
/snapshot delete baseline --force

Without --force, an existing noninteractive save fails rather than overwriting, and noninteractive deletion fails rather than deleting.

Snapshots are stored under:

~/.pi/agent/pi-session-snapshot/<name>.jsonl

Snapshot names may contain letters, numbers, dots, underscores, and hyphens. They must begin and end with a letter or number; paths, whitespace, and traversal are rejected. Lowercase kebab-case is recommended.

Start Pi from a snapshot

Use Pi's native fork option:

pi --fork ~/.pi/agent/pi-session-snapshot/baseline.jsonl

Other launch-time flags still compose with the fork:

pi \
  --fork ~/.pi/agent/pi-session-snapshot/baseline.jsonl \
  --model openai/gpt-5.4 \
  --thinking high

Pi does not allow --fork together with --session, --continue, --resume, or --no-session.

Semantics

Saving extracts only the current root-to-leaf session path. Alternate branches are omitted. Messages, tool calls/results, compactions, model/thinking changes, and applicable extension entries on the selected path remain part of the Pi session history.

Loading creates a new session in the current working directory. The snapshot remains unchanged as the restored session continues. The active restored path can be branched normally after loading; it starts from the saved path, not from the source session's omitted branches.

If a restored session receives no new meaningful activity, the extension makes a best-effort attempt to remove its otherwise-unused session file during graceful shutdown or session replacement. A session that starts an agent turn or gains a new message is retained. Hard crashes can leave a file behind.

Security

Session snapshots can contain prompts, model responses, tool output, paths, and other sensitive conversation context. The extension creates its snapshot directory and files with restrictive permissions where supported. Protect and review snapshots as you would normal Pi session files.

Development

npm run typecheck
npm run test
npm run build
npm run format:check
npm pack --dry-run

npm run format:check verifies formatting without changing files. Use npm run format only for intentional package-wide reformatting. For focused work, format only the paths you changed, for example npx prettier --write src/ui/flow.ts.

Automated filesystem tests use isolated temporary directories and do not touch the real Pi agent directory.

License

MIT