pi-excursion

Modal fork-and-return conversations for Pi.

pi-excursion suspends the current conversation, switches into a real interactive session fork, and resumes the parent only when you explicitly return or discard the excursion. The child can contain any number of messages and tool calls; only an approved return packet is added to the parent context.

Install

pi install npm:pi-excursion

For development from a local checkout:

pi -e ./index.ts

Commands

/excursion [goal]

Fork the current active branch and enter it as the active Pi session:

/excursion compare option 1 and option 2

The parent session is no longer active and remains unchanged on disk. Continue chatting normally in the child.

The footer shows the current nesting level and a one-line description of the immediate parent directly beneath the cwd path:

~/project (main)
excursion · depth 3 · parent: Compare storage options for agent state · /return or /discard
↑12.4k ↓2.1k 18.3%/200k                                      model-name

The parent description uses its excursion goal when nested, otherwise its session name or latest user message. It is truncated to keep the footer usable.

Excursions may be nested. Returning or discarding resumes the immediate parent, and the footer depth and parent description update automatically. The indicator is restored after /resume or restarting Pi.

/return <focus>

Run one reducer model call over the excursion context, asking it to select only information relevant to the focus:

/return the conclusions and evidence about option 1

The generated packet opens in Pi's editor. You can edit it before approval. Cancelling the editor leaves you in the excursion. Confirming it switches back to the parent, injects only the approved packet, and triggers the parent agent.

/return-exact [text]

Skip the reducer and edit a literal return packet:

/return-exact Option 1 was rejected because the API cannot preserve ordering.

/discard

Resume the parent without adding anything to its model context. The child session remains saved.

Persistence

Each child session gets a private sidecar next to its JSONL session file:

<child-session>.jsonl.pi-excursion.json

It records the immediate parent, fork point, goal, and status. This allows /return and /discard to keep working after restarting or resuming the child session.

The return packet is stored in the parent as a pi-excursion-return custom message. Its visible content is sent to the model; child-session metadata remains in message details and is not sent to the model.

Behavior and limitations

• Interactive TUI mode only.
• The current session must be persisted and have at least one entry.
• The reducer uses the child's current model and credentials.
• If the child compacted after the fork, the reducer uses the compaction-aware child context and may see summarized parent context as well.
• Conversation isolation does not isolate filesystem changes. Child edits affect the same working directory.