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

# Thin zsh launchers and composable command families

Wrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable.

## Related working material

- [Thin zsh launchers and composable command families — prompts and exercises](/topics/factory-zsh-launchers-practice/)
- [Thin zsh launchers and composable command families — questions and tradeoffs](/topics/factory-zsh-launchers-questions/)
- [Thin zsh launchers and composable command families — worked example](/topics/factory-zsh-launchers-worked-example/)

## TL;DR

- One working set of dotfiles runs Codex, Claude Code, and pi behind two-letter functions — launch, resume, fork, and second accounts each cost two or three keystrokes.
- You leave with four drop-in wrapper files (Codex, Claude Code, pi, and the full `pir` family) plus prompts that make your own agent build the next family for you.
- The one move: **wrap → compose → cheat-sheet → verify with `zsh -n`**. It took five minutes to build the whole pi family live.

 Have your agent set this up — paste this into it:

``` text
Fetch https://sacred-ritual-w7as.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.
```

## What launching an agent actually costs

You start a coding agent many times a day, and each launch needs the same environment variable, the same config override, and the same sandbox flag. Leaning on shell history means sometimes launching with a flag missing — which is worse than a failed launch, because the agent starts in a different permission posture than you expect. This is the raw Codex invocation behind the presenter's daily driver:

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

Nobody types that twice. The dotfiles reduce it to one letter, and hang the whole session vocabulary off that letter. This is the real wrapper plus its resume/fork family, drop-in ready:

``` text
# codex.zsh — Codex behind one letter, sessions behind two.
# Placeholders (comments only — nothing below needs editing):
#   <personal-account> = the login that owns ~/.codex
# Safety trade: --dangerously-bypass-approvals-and-sandbox removes approval
# prompts. Keep it only if you accept unattended file and shell access.

unalias x 2>/dev/null
x() {
  # Default account: <personal-account> via ~/.codex
  CODEX_HOME="${CODEX_PRIMARY_HOME:-$HOME/.codex}" \
    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
    --dangerously-bypass-approvals-and-sandbox "$@"
}

# The resume/fork family: every helper routes through x, so a future fix
# to x fixes the whole family for free.
unalias xr xrl xrm xf 2>/dev/null
xr()  { x resume "$@"; }         # pick a session to resume
xrl() { x resume --last "$@"; }  # jump into the most recent session
xrm() { x resume m "$@"; }       # resume the session named "m"
xf()  { x fork "$@"; }           # fork: xf <id|name> [prompt]
```

## Why functions, not aliases

An alias substitutes text. It cannot take a positional argument in the middle, cannot run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow these helpers, which is why every definition starts with `unalias <name> 2>/dev/null`. The same wrapper shape repeats across a second agent:

``` 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 "$@"
}
```

Functions also absorb upstream bugs. pi's lockfile dependency expects a directory at `auth.json.lock`; a stray regular file there causes recurring auth failures. The wrapper heals it on every launch, so the bug lives in one function instead of in your memory:

``` text
# pi.zsh — wrappers absorb upstream bugs so you don't have to remember them.
# pi's proper-lockfile dependency expects a directory at auth.json.lock; a
# stray regular file there causes recurring ENOTDIR auth failures.

unalias pi 2>/dev/null
pi() {
  local agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
  local auth_lock="$agent_dir/auth.json.lock"
  if [[ -f "$auth_lock" && ! -L "$auth_lock" ]]; then
    rm -f -- "$auth_lock"
  fi
  command pi "$@"
}
```

## Families compound: resume, fork, and second accounts

A single wrapper saves keystrokes; the payoff compounds when wrappers call wrappers. Since `x` owns the account and the flags, every session action is a one-line composition on top of it. The deepest member of the family forks a session, compacts the fork, and resumes it — still routed through `x`:

``` text
xfmc() {  # fork session "m" → compact the fork → resume it
  local fork_id
  fork_id="$(_codex_app_server_fork_compact_latest m)" || return 1
  print -r -- "$fork_id"
  _codex_cmux_name_current_tab
  x resume "$fork_id" "$@"
}
# the two _codex_* helpers live elsewhere in the dotfiles — shown for shape, not for pasting
```

Second accounts work the same way: `x2` points `CODEX_HOME` at `~/.codex-work`, a directory built by a helper that symlinks every top-level entry of the primary home *except* auth files, and refuses to run if an auth file ever becomes a symlink. Accounts share sessions and config, never credentials. A family this large needs a memory aid, so it prints its own: running `x-` lists every helper, straight from the file that defines them.

``` 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 prompt builder picks the agent last

Wrappers fix the launch, but not a subtler mistake: deciding which agent to use before you have written the prompt. The `p` command — a separate terminal program, "Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code" — inverts the order. Compose the prompt first, then send it to any configured target: one prompt can go to any of three agents across five accounts. Helpers like `p-f` and `p-c` close the loop by handing the finished prompt back to the zsh fork/resume functions.

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

You can rehearse without launching anything: `p --print-prompt "explain this repo"` prints the composed prompt and exits.

## The recipe, proved on pi

The claim that this repeats "in minutes" is testable, and the workshop tests it live. pi had a base wrapper but no session helpers. Step one is always the same — ask the CLI what it can do instead of guessing:

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

Each flag becomes one short function, the family gets a `pi-` cheat sheet in the `x-` style, and the whole file verifies with `zsh -n` plus a stub test before it ever touches a real shell. The finished file is printed complete in the [agent guide above](https://sacred-ritual-w7as.here.now/#agent-guide) — five helpers and a cheat sheet, built in about five minutes. The recipe: **wrap** the flags you can't remember, **compose** wrappers into families, **document** with a `fn-` help function, **repeat** for every new agent CLI.

## Appendix

### Limits & caveats

- **Safety trade:** `--dangerously-bypass-approvals-and-sandbox` (Codex) and `--dangerously-skip-permissions` (Claude Code) remove approval prompts. The wrappers make that posture deliberate and visible in one place, but they do not make it safe. Do not copy those flags unless you accept unattended file and shell access.
- **Drift risk:** composed families inherit fixes but also breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function lowers the cost of the audit; it does not remove the need for one.
- **Stub tests prove wiring, not behavior:** the success check proves each helper passes the intended flags. A live `pir` only opens a session picker when pi has saved sessions on that machine.
- **"Five minutes" is the presenter's estimate** for the live walkthrough, not a measurement.
- **One machine's configuration:** all evidence comes from one working set of dotfiles, version-specific snapshot. Treat specific flags as examples, not standards. The `p` target list is one machine's config file, not a tool default. No comparison was made with shell-history tools or command launchers.
- **Version pinning:** pi flags were captured from pi v0.80.10; re-run `--help` against your version.

## Original references

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