Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.
The session
pi had a base wrapper but no session helpers — the whole point of the walkthrough is that the gap closes in minutes. This transcript restages the section's scripted walkthrough as prompts to a coding agent; every output shown is the captured output from a prior session.
You
Run pi --help and pull out the session flags — resume, continue, fork, whatever it actually ships.
Agent
Ran the help command and filtered for the session verbs:
$ pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session"
--continue, -c Continue previous session
--resume, -r Select a session to resume
--fork <path|id> Fork specific session file or partial UUID into a new session
--name, -n <name> Set session display name
--no-session Don't save session (ephemeral)
First beat is always reconnaissance. You never invent verbs — every flag the CLI ships is a candidate wrapper, and nothing else is.
You
Wrap each flag as a two- or three-letter function in pi-utils.zsh, following my x-family convention: unalias guard first, one short function per flag, comment on the same line.
Agent
Wrote the one-liners. Each is a single line on top of the existing pi wrapper — the one that already heals the auth.json.lock bug before launching the binary:
unalias pir 2>/dev/null
pir() { pi --resume "$@"; } # pick a session to resume (pi resume)
unalias pic 2>/dev/null
pic() { pi --continue "$@"; } # continue the most recent session
unalias pif 2>/dev/null
pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt]
Composition, not duplication: the flags live in exactly one place. This is the same shape as xr() { x resume "$@" } in the Codex family — a future fix to the base wrapper fixes every helper for free.
You
pin takes an argument — a session name. Guard it so it fails loudly with usage instead of launching with a blank name.
Agent
unalias pin 2>/dev/null
pin() { # start a named session: pin <name> [prompt]
local name="${1:?Usage: pin <name> [prompt...]}"; shift
pi --name "$name" "$@"
}
Also added pit for --no-session throwaway runs.
The one wrapper that outgrows a one-liner earns a body — but only just. Guard clauses over silent failure.
You
Finish with the cheat sheet: a pi- function that prints the whole family, the way x- does for the Codex family.
Agent
Wrote pi- — a name array plus a description map, printed as an aligned table. Its output is in the verification run below.
Every family ships its own cheat sheet — the fn- convention. Six months from now, pi- answers "what did I name these?" without leaving the shell.
You
Verify without launching anything real: syntax check the file, then prove each helper passes the right flag.
Agent
Ran zsh -n, then a stub test that shadows pi with a function so nothing actually launches:
zsh -n ~/.zsh-wrappers/pi-utils.zsh && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'
syntax OK
pi Base wrapper: heals the auth.json.lock bug, then runs the pi binary.
pir Resume: open the session picker (pi --resume).
pic Continue: jump straight back into the last session (pi --continue).
pif Fork a session into a new one: pif <path|id> [prompt].
pin Start a named session: pin <name> [prompt].
pit Throwaway: run without saving a session (pi --no-session).
[stub pi] --resume --check
The stub proves wiring — which flags each helper passes — not behavior. A live pir opens pi's session picker only when saved sessions exist on the machine.
Agent
File landed. Complete and drop-in ready:
# pi-utils.zsh — the "pir" walkthrough result
# Built live at the workshop following the same recipe as the x/xr family.
# Source it: source ~/.zsh-wrappers/pi-utils.zsh then run: pi-
# Recipe step 0 — the base wrapper already exists in the dotfiles
# (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real
# pi binary. Every helper below composes on top of `pi`, never the raw binary.
# Recipe step 1 — read the CLI's own session flags:
# pi --help | grep -E "resume|continue|fork|name"
# --continue, -c Continue previous session
# --resume, -r Select a session to resume
# --fork <path|id> Fork a session into a new session
# --name, -n Set session display name
# Recipe step 2 — wrap each flag as a two/three-letter function.
unalias pir 2>/dev/null
pir() { pi --resume "$@"; } # pick a session to resume (pi resume)
unalias pic 2>/dev/null
pic() { pi --continue "$@"; } # continue the most recent session
unalias pif 2>/dev/null
pif() { pi --fork "$@"; } # fork a session: pif <path|id> [prompt]
unalias pin 2>/dev/null
pin() { # start a named session: pin <name> [prompt]
local name="${1:?Usage: pin <name> [prompt...]}"; shift
pi --name "$name" "$@"
}
unalias pit 2>/dev/null
pit() { pi --no-session "$@"; } # throwaway session (nothing saved)
# Recipe step 3 — every family ships its own cheat sheet (the x- convention).
pi-() {
local -a fn_name=(pi pir pic pif pin pit)
local -A fn_desc=(
pi 'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'
pir 'Resume: open the session picker (pi --resume).'
pic 'Continue: jump straight back into the last session (pi --continue).'
pif 'Fork a session into a new one: pif <path|id> [prompt].'
pin 'Start a named session: pin <name> [prompt].'
pit 'Throwaway: run without saving a session (pi --no-session).'
)
local fn
for fn in "${fn_name[@]}"; do
printf '%-4s %s\n' "$fn" "${fn_desc[$fn]}"
done
}
Five prompts, one file. The recipe the transcript demonstrates — wrap → compose → document → repeat — is the whole section; it repeats for every new agent CLI. This file and the full launcher family (agent-launchers.zsh) are downloadable attachments — grab the install block on the section guide.
Run this session yourself
Paste this into your own coding agent to replay the whole session against your machine — it is the same prompt from the section guide's prompt library.
Build me a two-letter zsh wrapper family for the pi CLI.
1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.
2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> "$@"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`.
3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.
4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:
zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'
Expect: [stub pi] --resume --check
5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.