pi-cutlery — multi-session tools for Pi

A small toolbox for Pi workflows that span multiple sessions. Current center of gravity:

• startup session forking
• tmux pane spawning
• session-control-friendly worker flows

tl;dr

• Problem: Pi has good session primitives, but adjacent-session workflows still need too much manual tmux and shell glue.
• Solution: pi-cutlery adds:
  • --fork-session <id>
  • /termfork
  • /term
  • tmux_new_pi
• Install: pi install npm:pi-cutlery

install

npm:

pi install npm:pi-cutlery

git:

pi install git:github.com/lajarre/pi-cutlery@<ref>

local path:

pi install /absolute/path/to/pi-cutlery

local project install:

pi install -l /absolute/path/to/pi-cutlery

Restart Pi after install.

30-second quickstart

Startup fork by full UUID or unique prefix:

pi --fork-session <session-id>
pi --fork-session 7649c823 "continue from here"

Fork the current live session into a new tmux pane:

/termfork

Open a fresh Pi worker in a new tmux pane:

/term

Agent-driven fresh worker spawn:

tool: tmux_new_pi

why pi-cutlery

Pi already has the primitives for rich multi-session work:

• durable sessions
• session-control sockets
• tmux-friendly terminal behavior

pi-cutlery adds the missing workflow blades around those primitives.

Use it when you want to:

• branch an exploratory thread without mutating the source session
• create an adjacent worker pane from inside Pi
• steer a child session over session-control after spawn
• keep parent and child visible side-by-side in tmux

common recipes

startup fork

pi --fork-session <session-id>

startup fork with session-control

pi --session-control --fork-session <session-id>

fork current live session into a tmux pane

/termfork

Default v1 behavior:

• horizontal tmux split
• detached pane (parent keeps focus)
• child starts with --session-control

open a fresh worker pane

/term

Default v1 behavior:

• horizontal tmux split
• detached pane
• fresh child session
• child starts with --session-control
• current session gets a visible spawn report with child session id/path

agent-driven worker spawn

tmux_new_pi creates the same fresh worker as /term and returns structured metadata:

• sessionId
• sessionFile
• cwd
• paneId when tmux reports one
• split

drive the spawned child over session-control

After spawn, use the child session id with your existing control flow.

Example shell form:

pi -p --session-control \
  --control-session <child-session-id> \
  --send-session-message "run a focused experiment" \
  --send-session-wait turn_end

full reference

--fork-session

Given a source session id (full UUID or unique leading prefix), the extension:

1. resolves the source session by id prefix
2. creates a forked session file via SessionManager.forkFrom(...)
3. re-execs Pi on the new fork with --session <fork-path>
4. keeps the source session file unchanged

Syntax:

pi --fork-session <session-id> [pi-options...] [@files...] [prompt...]

/termfork

Interactive command.

Behavior:

• requires tmux
• requires a persisted current session
• forks the current live session from the parent side
• opens a new detached horizontal tmux pane
• launches child Pi on the known fork path
• enables --session-control in the child
• leaves a visible spawn report in the current session

V1 command contract:

• no args
• non-empty args are rejected

/term

Interactive command.

Behavior:

• requires tmux
• creates a fresh child session from the parent side
• opens a new detached horizontal tmux pane
• launches child Pi on the known fresh session path
• enables --session-control in the child
• leaves a visible spawn report in the current session

V1 command contract:

• no args
• non-empty args are rejected

tmux_new_pi

LLM-callable tool.

Behavior:

• same spawn semantics as /term
• emits the same visible spawn report in the current session
• returns structured metadata in tool details

V1 tool contract:

• empty parameter object
• no prompt parameter yet
• if you want to task the child immediately, spawn first, then use your session-control send step

source resolution for --fork-session

Matching is against session.header.id.startsWith(<token>) only.

No matching by name, prompt text, or other filename text.

Lookup order:

1. call SessionManager.list(cwd, sessionDir?)
2. local matches are matches with session.cwd === process.cwd()
3. one local match => use it
4. multiple local matches => fail as ambiguous local
5. no local match and no --session-dir => call SessionManager.listAll()
6. one global match => use it
7. multiple global matches => fail as ambiguous global
8. none => fail as no match

--session-dir

--session-dir <dir> and --session-dir=<dir> are recognized for startup forking.

Current term-tools pane commands use the current session manager's storage scope when they materialize child sessions.

tmux contract

Pane-spawning features are tmux-first in v1.

Exact default split shape:

tmux split-window -h -d -P -F '#{pane_id}' -c <cwd> '<child-command>'

Meaning:

• -h = horizontal split
• -d = detached pane, keep focus in parent
• -P -F '#{pane_id}' = capture pane id for reporting

session-control contract

Children spawned by /termfork, /term, and tmux_new_pi enable --session-control by default.

The parent already knows the child session id from parent-side session materialization, so it can steer the child immediately if session-control is available in the environment.

loading contract

This is an extension/package feature, not a built-in core Pi feature.

Supported contract:

• install pi-cutlery as a Pi package
• restart Pi
• use the commands/flag/tool from that installed environment

Not guaranteed in v1:

• ad hoc -e ./... loading for tmux child panes without an installed package path reachable from the child environment

failure modes

• outside tmux: /termfork, /term, and tmux_new_pi fail clearly
• non-persisted current session: /termfork fails clearly
• tmux spawn failure after materialization: created session file may be kept for recovery and the error reports that path
• startup fork conflicts remain the same as before:
  • --session <path>
  • --continue, -c
  • --resume, -r
  • --no-session
  • --mode rpc, --mode json

for you / not for you

Use pi-cutlery if you want a branchable, pane-friendly session workflow in Pi and you like orchestrating work across multiple sessions.

Skip it if you need:

• message-level forking
• non-Node launcher support
• non-tmux pane orchestration as the primary target
• a general tmux management framework
• a session browser UI

known differences and out of scope

Today, pi-cutlery ships these workflow blades:

• --fork-session
• /termfork
• /term
• tmux_new_pi

It intentionally composes with:

• Pi's existing session-control behavior
• your own tmux layout and shell scripts

It still does not add:

• message-level fork primitives
• a custom socket protocol
• general tmux automation beyond these spawn helpers
• session browsing UI
• prompt-passthrough to child pane spawns in v1

prerequisites

• Pi with extension/package support enabled
• a Node-based Pi launcher shape for startup forking
• tmux for /termfork, /term, and tmux_new_pi
• an existing session id only when using --fork-session