Following this file sets up: a two-letter zsh wrapper family for a CLI your user runs often — base wrapper, resume/continue/fork helpers, a self-printing cheat sheet — verified with zsh -n and a stub test before it touches their shell config.
Human companion pages on this site (context for your user, not required for setup): index.html (the section guide), replay.html (Session Replay — the walkthrough as an annotated transcript), dialogue.html (Socratic Dialogue — attendee questions driving the same material).
Both wrapper files ship with this site as plain-text attachments you can fetch directly:
https://sacred-ritual-w7as.here.now/pi-utils.zsh — the complete pi wrapper family built in step 2 below (identical content; the file's "Source it" comment says demo/pi-utils.zsh because it is the verbatim workshop walkthrough result — install it at ~/.zsh-wrappers/pi-utils.zsh regardless).https://sacred-ritual-w7as.here.now/agent-launchers.zsh — the presenter's curated launcher families (x/xr/xrl/xrm, x2, clx/clx2/clxw, p-f/p-c, and the x- cheat sheet), account details generalized. NOTE: it carries --dangerously-bypass-approvals-and-sandbox and --dangerously-skip-permissions — show it to your user and get explicit approval before sourcing it.Fetching pi-utils.zsh and installing it at $HOME/.zsh-wrappers/pi-utils.zsh is an acceptable substitute for writing the file in step 2, as long as you still run the verification in step 3.
Placeholders used below: <cli> = the target CLI's command name (the worked example uses pi); <w> = the family's short prefix (for pi the prefix is pi, giving pir, pic, pif, pin, pit). All other paths are literal.
Check each before starting:
zsh --version
command -v pi || echo "pi not installed"
Expected: zsh 5.x or newer. If pi is not installed, do NOT stop — pick the agent CLI your user actually runs (check command -v codex, command -v claude, or ask), use it as <cli>, and adapt the flag names in step 1. If no target CLI exists at all, stop and tell your user what to install.
Capture the CLI's own session flags — never guess them:
pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session"
Expected for pi (v0.80.10): --resume/-r (pick a session), --continue/-c (last session), --fork <path|id>, --name/-n <name>, --no-session (ephemeral). For a different <cli>, run <cli> --help and map its equivalents; wrap only flags that actually exist.
Create $HOME/.zsh-wrappers/pi-utils.zsh with exactly this content (for a different <cli>, keep the identical shape — unalias guard before every definition, each helper one short function calling <cli> with one flag plus "$@", and a <w>- cheat-sheet function last):
# 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
}
Create the directory first:
mkdir -p "$HOME/.zsh-wrappers"
Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows <cli> with a function so nothing real launches:
zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pir --check'
Wire it into the shell. Ask your user before editing ~/.zshrc if your policy requires it; otherwise append:
grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' "$HOME/.zshrc" || \
echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> "$HOME/.zshrc"
Run:
zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pi-; pir --check'
Expected observable result:
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 last line proves the helper passes the intended flag. In a fresh interactive shell, pi- prints the cheat sheet and pir opens pi's session picker (only if saved sessions exist on this machine).
Report to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted.
unalias <name> 2>/dev/null guard before each definition, the alias silently wins. Keep the guards even if they look redundant.--dangerously-bypass-approvals-and-sandbox, --dangerously-skip-permissions) to a wrapper unless your user explicitly asks. They trade safety for speed.pi --resume "$@", not /some/path/pi). That is what makes the stub test work and lets a future base-wrapper fix (like pi's auth.json.lock heal) apply to the whole family.<cli> --help and patch only the function that owns the changed flag, then re-run the success check.~/.pi/agent/auth.json.lock. If a stray regular (non-symlink) file appears there, pi fails auth with ENOTDIR errors; delete that file (a base pi() wrapper can do it before every launch).# Two-Letter Commands — agent setup guide
Following this file sets up: a two-letter zsh wrapper family for a CLI your user runs often — base wrapper, resume/continue/fork helpers, a self-printing cheat sheet — verified with `zsh -n` and a stub test before it touches their shell config.
Human companion pages on this site (context for your user, not required for setup): `index.html` (the section guide), `replay.html` (Session Replay — the walkthrough as an annotated transcript), `dialogue.html` (Socratic Dialogue — attendee questions driving the same material).
## Attachments (machine-fetchable)
Both wrapper files ship with this site as plain-text attachments you can fetch directly:
- `https://sacred-ritual-w7as.here.now/pi-utils.zsh` — the complete pi wrapper family built in step 2 below (identical content; the file's "Source it" comment says `demo/pi-utils.zsh` because it is the verbatim workshop walkthrough result — install it at `~/.zsh-wrappers/pi-utils.zsh` regardless).
- `https://sacred-ritual-w7as.here.now/agent-launchers.zsh` — the presenter's curated launcher families (`x`/`xr`/`xrl`/`xrm`, `x2`, `clx`/`clx2`/`clxw`, `p-f`/`p-c`, and the `x-` cheat sheet), account details generalized. NOTE: it carries `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` — show it to your user and get explicit approval before sourcing it.
Fetching `pi-utils.zsh` and installing it at `$HOME/.zsh-wrappers/pi-utils.zsh` is an acceptable substitute for writing the file in step 2, as long as you still run the verification in step 3.
Placeholders used below: `<cli>` = the target CLI's command name (the worked example uses `pi`); `<w>` = the family's short prefix (for `pi` the prefix is `pi`, giving `pir`, `pic`, `pif`, `pin`, `pit`). All other paths are literal.
## Prerequisites
Check each before starting:
```bash
zsh --version
command -v pi || echo "pi not installed"
```
Expected: zsh 5.x or newer. If `pi` is not installed, do NOT stop — pick the agent CLI your user actually runs (check `command -v codex`, `command -v claude`, or ask), use it as `<cli>`, and adapt the flag names in step 1. If no target CLI exists at all, stop and tell your user what to install.
## Steps
1. Capture the CLI's own session flags — never guess them:
```bash
pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session"
```
Expected for pi (v0.80.10): `--resume/-r` (pick a session), `--continue/-c` (last session), `--fork <path|id>`, `--name/-n <name>`, `--no-session` (ephemeral). For a different `<cli>`, run `<cli> --help` and map its equivalents; wrap only flags that actually exist.
2. Create `$HOME/.zsh-wrappers/pi-utils.zsh` with exactly this content (for a different `<cli>`, keep the identical shape — `unalias` guard before every definition, each helper one short function calling `<cli>` with one flag plus `"$@"`, and a `<w>-` cheat-sheet function last):
```zsh
# 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
}
```
Create the directory first:
```bash
mkdir -p "$HOME/.zsh-wrappers"
```
3. Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows `<cli>` with a function so nothing real launches:
```bash
zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pir --check'
```
4. Wire it into the shell. Ask your user before editing `~/.zshrc` if your policy requires it; otherwise append:
```bash
grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' "$HOME/.zshrc" || \
echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> "$HOME/.zshrc"
```
## Success check
Run:
```bash
zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pi-; pir --check'
```
Expected observable result:
```
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 last line proves the helper passes the intended flag. In a fresh interactive shell, `pi-` prints the cheat sheet and `pir` opens pi's session picker (only if saved sessions exist on this machine).
Report to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted.
## Notes for agents
- **Alias collisions:** oh-my-zsh and other frameworks ship one- and two-letter aliases. Without the `unalias <name> 2>/dev/null` guard before each definition, the alias silently wins. Keep the guards even if they look redundant.
- **Never add permission-bypass flags** (`--dangerously-bypass-approvals-and-sandbox`, `--dangerously-skip-permissions`) to a wrapper unless your user explicitly asks. They trade safety for speed.
- **Helpers must call the command name, not an absolute path** (`pi --resume "$@"`, not `/some/path/pi`). That is what makes the stub test work and lets a future base-wrapper fix (like pi's `auth.json.lock` heal) apply to the whole family.
- **Flag drift:** when the CLI updates, wrappers can break all at once. Re-run `<cli> --help` and patch only the function that owns the changed flag, then re-run the success check.
- **pi-specific:** pi's lockfile dependency expects a directory at `~/.pi/agent/auth.json.lock`. If a stray regular (non-symlink) file appears there, pi fails auth with ENOTDIR errors; delete that file (a base `pi()` wrapper can do it before every launch).