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:

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:

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:

    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):

    # 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"
    
  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:

    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:

    grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' "$HOME/.zshrc" || \
      echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> "$HOME/.zshrc"
    

Success check

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.

Notes for agents

# 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).