Agentic Software Factory · 2026-07-17 · Custom zsh Functions

Session Replay: watch pir get built

The section's finale as an annotated transcript: five prompts, one self-documenting wrapper family. Watch the beats, then lift the file that lands at the end.

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.

Grounding: this transcript restages the section's scripted walkthrough beat for beat; every output block is captured output from a prior session, and the final file is the walkthrough result verbatim (one comment path changed from the project's demo/ dir to ~/.zsh-wrappers/ for drop-in use). Caveats — bypass-flag safety trades, wrapper drift, auth isolation — live in the section guide's appendix.