---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-zsh-launchers-worked-example"
title: "Thin zsh launchers and composable command families — worked example"
---

# Thin zsh launchers and composable command families — worked 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:

``` text
$ 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:

``` text
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

``` text
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:

``` text
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'
```

``` text
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:

``` text
# 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](https://sacred-ritual-w7as.here.now/index.html).

## 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](https://sacred-ritual-w7as.here.now/index.html) prompt library.

``` text
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.
```

## Original references

- [Thin zsh launchers and composable command families — worked example](https://sacred-ritual-w7as.here.now/replay.html)
