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

# Thin zsh launchers and composable command families — questions and tradeoffs

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

## The room asks

Why not just aliases?

An alias substitutes text. It can't take a positional argument in the middle, can't run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow half of these helpers. A function passes `"$@"` straight through, and an `unalias` guard makes it win any collision. Here's what my `x` function is hiding:

``` text
CODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox
```

And once `x` owns that, the entire resume family is one-line compositions on top of it:

``` text
xr()  { x resume "$@"; }         # pick a session to resume
xrl() { x resume --last "$@"; }  # jump into the most recent session
```

Okay, but I run two Codex accounts. Doesn't this fall apart the moment auth is involved?

That's what `x2` is: the same wrapper pointed at a second home directory (`CODEX_HOME=~/.codex-work`) that a helper builds by symlinking every top-level entry of the primary home *except* the auth files — and it refuses to run if an auth file would ever become a symlink. Sessions and config: shared. Credentials: never. The same trick with `CLAUDE_CONFIG_DIR` gives Claude Code a second account, and that one is simple enough to lift right now:

``` text
# claude.zsh — same pattern, different agent.
# Placeholders (comments only — nothing below needs editing):
#   <work-account> = the login that owns ~/.claude-second
# Safety trade: --dangerously-skip-permissions removes permission prompts.

unalias clx clx2 clxw 2>/dev/null
clx()  { claude --dangerously-skip-permissions "$@"; }

clx2() {  # second account (<work-account>) — same UX, separate config dir
  local config_dir="${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}"
  mkdir -p "$config_dir" || return
  CLAUDE_CONFIG_DIR="$config_dir" claude --dangerously-skip-permissions "$@"
}

clxw() {  # launch inside a named worktree: clxw <name> [args]
  local name="$1"; shift
  CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@"
}
```

Isn't `--dangerously-bypass-approvals-and-sandbox` terrifying?

It should give you pause — the flag says so out loud. Bypass flags trade safety for speed, and the wrapper doesn't change that trade; it stops you re-deciding it forty times a day and makes the posture deliberate and visible in one place. If you don't want the bypass, your `x` simply doesn't include it — the pattern works exactly the same. Don't copy those flags unless you accept unattended file and shell access.

How do you remember fifteen two-letter functions?

I don't. Every family ends in a dash function that prints its own cheat sheet — `x-` for Codex, `pi-` for pi. The docs live where you type:

``` text
$ x-
x        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.
x2       Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.
xr       Resume a Codex session through the base x wrapper.
xrl      Resume the most recent Codex session through the base x wrapper.
xf       Run x fork; pass the conversation id/name first, then the prompt.
xfmc     Fork conversation m, compact the fork, then resume it interactively.
p-f      Compose a prompt in p, then fork using the prompt-builder --fork-from toggle.
# … full listing covers 35 helpers
```

The CLI updates and renames a flag. Now every wrapper is broken at once, right?

Yes — that's the honest cost of composition: families inherit fixes *and* breakage. But the audit is cheap, because the same stub trick that verifies a new family also detects drift without launching anything:

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

Re-run `--help`, patch the one function that owns the changed flag, re-run the stub. The [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library has a drift-audit prompt that makes your agent do the whole pass.

You keep saying you "pick the agent last." What does that actually mean?

Wrappers fix the launch, but there's a subtler mistake: choosing the agent before you've written the prompt. The `p` command — a terminal prompt builder — inverts that. Compose the prompt first, then hand it to any configured target: one prompt can go to any of three agents across five accounts.

``` text
$ p target list
pi            pi     bin=pi
codex         codex  bin=codex  config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"
claude        claude bin=claude
work-profile       codex  bin=codex  CODEX_HOME=~/.codex-work  config=cli_auth_credentials_store="file" …
claude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second
claude-third  claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third
```

Helpers like `p-f` close the loop: compose in `p`, then fork the session and resume with the prompt — all free once the base wrappers exist.

A new agent CLI ships next month. How long before it feels like this?

About five minutes. Run the recipe: **wrap → compose → document → repeat**. We did it live for pi — read `--help` for the session flags, wrap each one, add the dash function, verify with a stub. The complete result, 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
}
```

Want to watch that file get built prompt by prompt? That's the [Session Replay](https://sacred-ritual-w7as.here.now/replay.html) page. Both 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).

Every function, flag, and output above comes from the section's verified sources — the presenter's dotfiles, captured CLI output, and the walkthrough result. Account emails are replaced with `<personal-account>` / `<work-account>` placeholders. Full caveats and provenance: the [section guide's](https://sacred-ritual-w7as.here.now/index.html) appendix.

## Original references

- [Thin zsh launchers and composable command families — questions and tradeoffs](https://sacred-ritual-w7as.here.now/dialogue.html)
