agent utilsPi package

sessions

Choices, control and continuity

Long-running agents need to ask questions without stalling, keep going without supervision, survive updates and restarts, and move between machines. These extensions handle the life of a session.

Asking questions

interactive_choice puts a bounded question in front of you and waits; async_choice posts one or many questions and lets the agent carry on. Both can be answered from almost anywhere.

One question, many ways to answerAn agent asks a question with interactive_choice, which blocks, or async_choice, which returns at once. The question enters one choice state machine in Pi. Answers can come from many inputs: the keyboard with arrows, j and k, numbers and Enter; push-to-talk speech; an Omni keystroke cast from another device; a ring controller; any Agent Host Protocol client such as a phone app; and the agent orchestrator's mobile decision queue. Whichever answers first settles the question exactly once, and the answer returns to the agent, as the tool result for a blocking choice or as a steering message for an async one. agent interactive_choice async_choice choice state one per question settles exactly once survives reload keyboard arrows · 1–9 · Enter push-to-talk spoken answer Omni cast from a device ring gesture controller AHP clients phone, web orchestrator mobile decisions the answer returns as the tool result, or as a steering message for async
One question, many ways to answer.Local and remote inputs feed the same state machine, so an answer from a phone and a keypress at the desk cannot both win.
A terminal dialog asking which validation path should run before the release, with three numbered options, the first selected, and key hints for moving, choosing, typing a reply, push-to-talk and cancelling.
A blocking choice.Arrows or j/k, a number, Enter; i to type a reply; Space to speak one.
A Pi session with a question sidebar showing two pending questions; the first has thirteen options.
Async questions.Ctrl+Alt+Q or /choices opens the sidebar; each answer is injected back to the agent as a steering message.

Working unattended

CommandDoes
/compact-nextCompact at the next finished reply or tool batch instead of aborting work, then resume without a new prompt where possible
/endless [delay=60]When the agent has fully settled, nudge it again after a delay, optionally compacting first; /endless off stops
/after 20m promptDeliver a prompt or command once, later, from durable session entries that survive a restart; no cron or background jobs
/git-behindWarn any agent whose checkout falls well behind its default branch
Copilot token refreshWhen a GitHub Copilot token goes missing mid-session, reload the stored credentials and retry the request once instead of stopping

Updating and restarting

CommandDoes
/updateUpdate Pi packages, reload the runtime and activate new tools
/reload-toolsReload extensions and make every registered tool visible to the model
/restartRe-exec Pi in place on the same session, keeping runtime flags but not the original prompt or @file arguments, so launch instructions are not replayed

Restart replaces the process rather than spawning a second Pi, so nothing competes for the terminal. Agents can request all three through tools; startup auto-update is opt-in.

Models and effort

Operators switch freely; agents are fenced in.

ForCommand or toolBoundary
Operator/m provider/model, /effort, /fastThe full model registry; /fast toggles a configured -fast sibling
Agentself_set_model, self_list_modelsOnly models on a whitelist in selfModelSelection.models; a missing or empty list means no switches
Agentself_set_effortOnly when the operator asked for it

Moving a session

/session-fork and the pi-session command copy a Pi session, history unchanged, to a worktree, another directory or another machine over SSH, set up Git at the exact commit and optionally open it in a terminal workspace:

pi-session fork --session id --remote host --herdr --focuspi-session pull --from host --session id      # from the destination, no reverse SSHpi-session status request-id

Each fork has a stable request id with a durable receipt, so an interrupted fork can be retried without duplicating it, and the copied history ends with a notice of where it moved.

Shells and pipes