Agentic Software Factory · 2026-07-17 · Custom zsh Functions

“Why not just aliases?”

The section as the workshop room actually runs it: skeptical questions drive the reveal, and each answer lands real code exactly where the question demands it.

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:

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:

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

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

$ x-
x        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.
x2       Egghead Codex (<work-account> / ~/.codex-egghead); 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:

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

$ 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
egghead       codex  bin=codex  CODEX_HOME=~/.codex-egghead  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:

# 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 page. Both this file and the full launcher family (agent-launchers.zsh) are downloadable attachments — grab the install block on the section guide.

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 appendix.