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