Thin zsh launchers and composable command families — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

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.

Source references