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:
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:
# 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:
# 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:
# 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:
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-egghead, 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.
$ 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 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.
$ 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
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:
$ 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 — 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.