Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.
Abstract
Tiny zsh functions are the cheapest layer of an agentic system. This document argues five steps: agent CLIs impose a real flag-recall tax; a two-letter wrapper function removes it; composing wrappers into families multiplies the payoff; a self-printing cheat sheet keeps the layer discoverable; and the recipe repeats for any new CLI, shown here by building a resume family for the pi agent. All evidence comes from one machine's working configuration, so treat the specific flags as examples, not standards.
Notice what launching an agent really costs
You start a coding agent many times a day. Each launch needs the same environment variable, the same config override, and the same sandbox flag. The common mistake is to lean on shell history: you search backward, hope the right variant surfaces, and sometimes launch with a flag missing. A launch with a missing flag is worse than a failed launch, because the agent starts in a different permission posture than you expect.
The dotfiles solve this with a one-letter function. The x function pins the Codex home directory, injects a config marker, and applies the sandbox-bypass flag in one place (source S1, conf.d/40-ai.zsh). 1
1. The config override sets CODEX_LOAD_ZSH_DSL="1" in the agent's shell environment. The same dotfiles use that marker to expose their shell helpers inside agent tool shells (S1, S3). ↩
# ~/.config/zsh/conf.d/40-ai.zsh — the real wrapper (email replaced)
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 "$@"
}
Figure 1. Source evidence: the x function, quoted from S1 with one comment edited to replace a personal email address.
Safety trade The --dangerously-bypass-approvals-and-sandbox flag removes the agent's approval prompts. The wrapper makes that posture deliberate and visible in one place, but it does not make it safe. Do not copy the flag into your own wrapper unless you accept unattended file and shell access.
Try the check yourself: run which x in a shell where the wrapper is loaded. If it prints a function body with every flag pinned, launches can no longer drift. If it prints nothing, or prints an alias, you are still paying the recall tax. Your next move is an inventory: write down every agent command you retyped this week.
Compare an alias with a defended function
The tempting shortcut is an alias. 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. A function can do all three. The dotfiles treat that last risk as real: nearly every definition starts with unalias <name> 2>/dev/null, because oh-my-zsh ships single-letter aliases that would otherwise shadow the function (S1).
The same wrapper shape repeats across a second agent. The clx family wraps Claude Code exactly the way x wraps Codex: base flags in the short name, an environment variable for the second account, a positional argument for worktrees (S1).
clx() { claude --dangerously-skip-permissions "$@"; }
clx2() {
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() {
local name="$1"; shift
CLAUDE_WORKTREE_NAME="$name" claude --worktree "$name" --dangerously-skip-permissions "$@"
}
Figure 2. Source evidence: three members of the Claude Code family, quoted from S1. Note what an alias cannot do here: clxw consumes its first argument before passing the rest through.
Wrappers also absorb upstream bugs. The pi wrapper deletes a malformed lock file before every launch, so a known failure in the pi agent's locking library never reaches the user (source S2, local.zsh). 2
2. The source comment explains the mechanism: pi's lockfile dependency expects a directory at auth.json.lock. A stray regular file there causes recurring auth failures, so the wrapper removes it (S2). ↩
The decision rule: reach for an alias only when the command is pure text substitution with no arguments, no environment, and no collision risk. Otherwise write a function with the unalias guard and "$@" pass-through. The feedback signal is the same as before — which <name> tells you which one you actually got.
Explain why composed families beat one-off wrappers
A single wrapper saves keystrokes. The compounding payoff appears when wrappers call other wrappers. If x owns the account and the flags, then every session action becomes a one-line composition on top of it — and inherits any future fix to x for free.
The dotfiles build a whole resume-and-fork vocabulary this way: xr resumes, xrl resumes the last session, xrm resumes a session named "m", and xfmc forks that session, compacts the fork, and resumes it — all routed through x (S1).
xr() { x resume "$@"; }
xrl() { x resume --last "$@"; }
xrm() { x resume m "$@"; }
xf() { x fork "$@"; }
xfmc() {
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" "$@"
}
Figure 3. Source evidence: the resume and fork family, quoted from S1. Each helper is a thin composition over x; only xfmc adds real logic.
Composition also solves multi-account work. The x2 function runs the same agent under a second account by pointing CODEX_HOME at a second directory that shares the primary's state through symlinks — while auth files stay local to each account (S1). 3
3. A helper named _codex_egghead_ensure_home builds the second home. It symlinks every top-level entry except auth-related names such as auth.json, and it refuses to run if the auth file ever becomes a symlink (S1). Accounts share sessions and config, never credentials. ↩
A family this large needs its own memory aid, and the dotfiles make the family print one. Running x- lists every helper with a one-line description, straight from the same file that defines them (S1; output captured in S3).
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.
Figure 4. Source evidence: excerpt of the x- cheat sheet captured the recorded snapshot (S3). Email addresses are replaced with placeholders; the full listing covers 35 helpers.
Drift risk Composed families inherit fixes, but they also inherit breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function reduces the cost of the audit; it does not remove the need for one.
The test for your own setup: pick your most common session action — resuming — and count the keystrokes it takes today. If the answer is more than three or four, you have found the first family worth building.
Choose the agent at prompt time, not alias time
Wrappers fix the launch. They do not fix a second, subtler mistake: deciding which agent to use before you have written the prompt. Once the prompt exists, you often realize it belongs to a different agent, a different account, or a forked copy of an old session.
The p command inverts the order. It is a separate terminal program — "Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code," in its own help text — that lets you compose the prompt first and then launch any configured target with it (S3).
$ p target list
pi pi bin=pi
codex codex bin=codex config=shell_environment_policy...
claude claude bin=claude
work-profile codex bin=codex CODEX_HOME=~/.codex-work ...
claude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second
claude-third claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third
Figure 5. Source evidence: launch targets captured the recorded snapshot (S3), abbreviated to fit. One prompt can go to any of three agents across five accounts.
The two layers then compose with each other. Helpers such as p-f and p-c open the prompt builder, and hand the finished prompt to a zsh function that forks a session, optionally compacts it, and resumes it (S1).
You can rehearse this without launching anything: p --print-prompt "explain this repo" prints the composed prompt and exits, and --dry-run skips the launch entirely (S3). If the printed prompt matches what you meant to send, the pipeline is wired correctly. The limit to keep in mind: the target list above is one machine's configuration file, not a default that ships with the tool.
Test the recipe: build a pi resume family
The claim that this recipe repeats "in minutes" is testable, and the workshop tests it live. The pi agent has a base wrapper but no session helpers yet. 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)
Figure 6. Source evidence: session flags from pi's own help output, version 0.80.10, captured the recorded snapshot (S3).
Each flag becomes one short function, and the family gets its own cheat sheet in the x- style. This is the exact file built for the workshop (source S4, demo/pi-utils.zsh).
pir() { pi --resume "$@"; } # pick a session to resume
pic() { pi --continue "$@"; } # continue the most recent session
pif() { pi --fork "$@"; } # fork a session: pif <path|id>
pin() { # start a named session
local name="${1:?Usage: pin <name> [prompt...]}"; shift
pi --name "$name" "$@"
}
pit() { pi --no-session "$@"; } # throwaway session
Figure 7. Source evidence: the new pi family, quoted from S4. A pi- cheat-sheet function completes the file.
$ zsh -n demo/pi-utils.zsh && echo "syntax OK"
syntax OK
$ zsh -fc 'pi() { echo "[stub pi] $@"; }; source demo/pi-utils.zsh; pir --check'
[stub pi] --resume --check
Figure 8. Derived display: the verification run from the recorded snapshot (S4), reformatted from the build log. A stub replaces the real binary, proving each helper passes the intended flags.
Evidence limit The stub test proves flag wiring, not end-to-end behavior. A live pir only opens the session picker when pi has saved sessions on that machine. The sources also do not measure the "five minutes" figure; it is the presenter's estimate for this walkthrough.
Run the same two commands against any wrapper file you write. Syntax check first, stub test second. If the stub echoes the flags you expected, load the file for real and watch pir open the picker. If it echoes something else, the bug is in your function, not in the agent — which is exactly where you want bugs to live.
Practical action
Apply the recipe to one agent CLI this week:
- Capture the exact launch command you retype most, flags and all.
- Wrap it:
unaliasguard, short function name, env pinning inside,"$@"at the end. - Compose the first family on top — resume is usually the highest-value action.
- Document with a
<name>-cheat-sheet function so the family stays discoverable. - Verify with
zsh -n, then a stub test, before sourcing it in your real shell.
Success looks like this: a week later, which shows functions instead of history searches, and the cheat sheet answers "what was that helper called?" without leaving the terminal. If a wrapper breaks after a CLI update, that is the drift caveat arriving on schedule — re-run the CLI's --help and adjust the one function that owns the changed flag.