Agentic Software Factory · 2026-07-17

Two-Letter Commands: Custom zsh Functions for Agent CLIs

Stop retyping flag-heavy agent launches. Wrap them in two-letter zsh functions, compose the wrappers into resume, fork, and account families, and rebuild the whole layer for any new CLI in minutes.

TL;DR

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

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.

Quick start

Sixty seconds, zero installs: build a wrapper family in a temp dir and prove it passes the right flags with a stub.

cd "$(mktemp -d)"
printf '%s\n' 'pir() { pi --resume "$@"; }' 'pic() { pi --continue "$@"; }' \
  'pi-() { printf "pir  resume\npic  continue\n"; }' > pi-utils.zsh
zsh -n pi-utils.zsh && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source pi-utils.zsh; pi-; pir --check'

Prompt library

Paste these into your own coding agent. Each one applies the recipe without you memorizing it.

Build a wrapper family for a CLI

any coding agent anywhere ~/.zsh-wrappers/pi-utils.zsh + passing stub test

Build me a two-letter zsh wrapper family for the pi CLI.

1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.
2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> "$@"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`.
3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.
4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:
   zsh -fc 'pi() { echo "[stub pi] $@"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'
   Expect: [stub pi] --resume --check
5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.

Mine your shell history for wrapper candidates

any coding agent anywhere a ranked top-5 list + one proposed wrapper file to review

Read my shell history (~/.zsh_history, or `fc -l 1` output I paste) and find the commands I retype most. Group near-identical long commands (same binary, same flags), rank the top 5 by length times repeat count, and for each one propose a two-letter zsh wrapper function: `unalias` guard first, environment pinning inside the function, `"$@"` pass-through at the end. Print all proposed functions in one file for me to review. Do not install or source anything yet.

Add a second account to an existing wrapper

any coding agent anywhere a <name>2 wrapper + an auth-isolated second home dir

I have a zsh wrapper function for an agent CLI and I want a second account with the same UX. Create a `<name>2` wrapper that launches the same CLI with its config env var (CODEX_HOME for codex, CLAUDE_CONFIG_DIR for claude) pointed at a second directory such as ~/.<cli>-second. Rules: create the directory if it is missing; if the tool benefits from shared state, symlink top-level entries from the primary home EXCEPT auth files (auth.json and similar) — auth stays local, never symlinked or copied; refuse to proceed if an auth file would end up shared or would become a symlink. Show me the wrapper and the ensure-home helper before running anything.

Audit wrappers for flag drift after a CLI update

any coding agent anywhere a drift report + patched wrapper files with before/after diff

My agent CLI just updated. Audit my wrapper functions for flag drift: (1) list every function in ~/.zsh-wrappers/*.zsh and the flags each one passes; (2) run `--help` for each wrapped binary and check that every flag still exists with the same meaning; (3) report renamed or removed flags and patch only the affected functions; (4) re-verify each patched file with `zsh -n` and a stub test that echoes the flags. Show me a before/after diff of every change.

Set it up (agent guide)

These steps mirror agent.md — the machine copy your agent fetches. They install the pi resume family built live at the workshop; the same shape works for any CLI.

  1. Create ~/.zsh-wrappers/pi-utils.zsh with exactly this content — the complete file from the live walkthrough:
    # 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
    }
  2. Wire it into your shell:
    mkdir -p ~/.zsh-wrappers
    # save the file above as ~/.zsh-wrappers/pi-utils.zsh, then:
    echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc
    exec zsh

Success check: syntax first, then a stub test that proves every helper passes the intended flags — 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'
syntax OK
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).
[stub pi] --resume --check

Attachments — take it home

Both wrapper files discussed on this page ship with the site as downloadable attachments: agent-launchers.zsh (the x/xr/x2, clx, and p-f/p-c families, curated from the presenter's dotfiles with account details generalized) and pi-utils.zsh (the complete pir walkthrough result). One block installs both:

mkdir -p ~/.zsh-wrappers
curl -fsSL https://sacred-ritual-w7as.here.now/agent-launchers.zsh -o ~/.zsh-wrappers/agent-launchers.zsh
curl -fsSL https://sacred-ritual-w7as.here.now/pi-utils.zsh -o ~/.zsh-wrappers/pi-utils.zsh
echo 'source ~/.zsh-wrappers/agent-launchers.zsh' >> ~/.zshrc
echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc

Read both files before sourcing them — the Codex and Claude wrappers carry the bypass/skip-permission flags discussed in the appendix. Open a new shell, then run x- and pi- to print the cheat sheets.

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.

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, verified 2026-07-16. 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.
Provenance
  • S1 — the presenter's zsh config ~/.config/zsh/conf.d/40-ai.zsh: x (~line 1126), resume/fork family (~1159–1181), clx family (~969–1007), x2 and its auth-isolating helper (~1036–1142), prompt-builder handoff (~1278–1297), x- help (~1304). Function bodies quoted directly.
  • S2 — ~/.config/zsh/local.zsh (~line 147): the pi() heal wrapper. The published drop-in version replaces the machine-specific "$PNPM_HOME/pi" call with command pi.
  • S3 — CLI output captured 2026-07-16 from x-, p --help, p target list, and pi --help (v0.80.10). Two email addresses replaced with <personal-account> / <work-account>; long lines abbreviated where marked with ….
  • S4 — demo/pi-utils.zsh from the workshop project, printed complete in the agent guide with one comment path changed from demo/ to ~/.zsh-wrappers/ for drop-in use; its verification log is the basis of the success-check output.
  • S5 — the workshop agenda brief, used only for scope and framing.
  • The liftable codex.zsh / claude.zsh blocks regroup S1 functions into standalone files (added unalias lines and placeholder headers); flags and bodies are otherwise verbatim. This page supersedes the earlier Scholarly Folio at this URL. One local script (app.js) adds copy buttons; the page reads fully without it. No external requests.