{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-zsh-launchers-worked-example",
  "slug": "zsh-launchers-worked-example",
  "title": "Thin zsh launchers and composable command families — worked example",
  "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Tools",
  "tags": [
    "zsh-launchers",
    "examples"
  ],
  "sources": [
    {
      "label": "Thin zsh launchers and composable command families — worked example",
      "url": "https://sacred-ritual-w7as.here.now/replay.html"
    }
  ],
  "sourceUnits": [
    "02-zsh/replay.html#The session",
    "02-zsh/replay.html#Run this session yourself"
  ],
  "collection": "factory",
  "categoryId": "tools",
  "wordCount": 1172,
  "url": "/topics/factory-zsh-launchers-worked-example/",
  "markdownUrl": "/markdown/factory-zsh-launchers-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-zsh-launchers-worked-example.json",
  "headings": [
    {
      "id": "the-session",
      "text": "The session",
      "level": 2
    },
    {
      "id": "run-this-session-yourself",
      "text": "Run this session yourself",
      "level": 2
    }
  ],
  "markdown": "# Thin zsh launchers and composable command families — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\npi 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.\n\nYou\n\nRun `pi --help` and pull out the session flags — resume, continue, fork, whatever it actually ships.\n\nAgent\n\nRan the help command and filtered for the session verbs:\n\n``` text\n$ pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n  --continue, -c        Continue previous session\n  --resume, -r          Select a session to resume\n  --fork <path|id>      Fork specific session file or partial UUID into a new session\n  --name, -n <name>     Set session display name\n  --no-session          Don't save session (ephemeral)\n```\n\nFirst beat is always reconnaissance. You never invent verbs — every flag the CLI ships is a candidate wrapper, and nothing else is.\n\nYou\n\nWrap 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.\n\nAgent\n\nWrote 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:\n\n``` text\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n```\n\nComposition, 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.\n\nYou\n\n`pin` takes an argument — a session name. Guard it so it fails loudly with usage instead of launching with a blank name.\n\nAgent\n\n``` text\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n```\n\nAlso added `pit` for `--no-session` throwaway runs.\n\nThe one wrapper that outgrows a one-liner earns a body — but only just. Guard clauses over silent failure.\n\nYou\n\nFinish with the cheat sheet: a `pi-` function that prints the whole family, the way `x-` does for the Codex family.\n\nAgent\n\nWrote `pi-` — a name array plus a description map, printed as an aligned table. Its output is in the verification run below.\n\nEvery family ships its own cheat sheet — the `fn-` convention. Six months from now, `pi-` answers \"what did I name these?\" without leaving the shell.\n\nYou\n\nVerify without launching anything real: syntax check the file, then prove each helper passes the right flag.\n\nAgent\n\nRan `zsh -n`, then a stub test that shadows `pi` with a function so nothing actually launches:\n\n``` text\nzsh -n ~/.zsh-wrappers/pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'\n```\n\n``` text\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\nThe 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.\n\nAgent\n\nFile landed. Complete and drop-in ready:\n\n``` text\n# pi-utils.zsh — the \"pir\" walkthrough result\n# Built live at the workshop following the same recipe as the x/xr family.\n# Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n# Recipe step 0 — the base wrapper already exists in the dotfiles\n# (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n# pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n# Recipe step 1 — read the CLI's own session flags:\n#   pi --help | grep -E \"resume|continue|fork|name\"\n#   --continue, -c   Continue previous session\n#   --resume, -r     Select a session to resume\n#   --fork <path|id> Fork a session into a new session\n#   --name, -n       Set session display name\n\n# Recipe step 2 — wrap each flag as a two/three-letter function.\n\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n\nunalias pit 2>/dev/null\npit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n# Recipe step 3 — every family ships its own cheat sheet (the x- convention).\npi-() {\n  local -a fn_name=(pi pir pic pif pin pit)\n  local -A fn_desc=(\n    pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n    pir 'Resume: open the session picker (pi --resume).'\n    pic 'Continue: jump straight back into the last session (pi --continue).'\n    pif 'Fork a session into a new one: pif <path|id> [prompt].'\n    pin 'Start a named session: pin <name> [prompt].'\n    pit 'Throwaway: run without saving a session (pi --no-session).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n```\n\nFive 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).\n\n## Run this session yourself\n\nPaste 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.\n\n``` text\nBuild me a two-letter zsh wrapper family for the pi CLI.\n\n1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.\n2. 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`.\n3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.\n4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'\n   Expect: [stub pi] --resume --check\n5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.\n```"
}
