{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-zsh-launchers",
  "slug": "zsh-launchers",
  "title": "Thin zsh launchers and composable command families",
  "summary": "Wrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable.",
  "category": "Tools",
  "tags": [
    "zsh",
    "factory"
  ],
  "sources": [
    {
      "label": "Thin zsh launchers and composable command families",
      "url": "https://sacred-ritual-w7as.here.now/"
    }
  ],
  "sourceUnits": [
    "02-zsh/index.html#TL;DR",
    "02-zsh/index.html#What launching an agent actually costs",
    "02-zsh/index.html#Appendix",
    "02-zsh/index.html#Why functions, not aliases",
    "02-zsh/index.html#Families compound: resume, fork, and second accounts",
    "02-zsh/index.html#The prompt builder picks the agent last",
    "02-zsh/index.html#The recipe, proved on pi"
  ],
  "collection": "factory",
  "categoryId": "tools",
  "wordCount": 1498,
  "url": "/topics/factory-zsh-launchers/",
  "markdownUrl": "/markdown/factory-zsh-launchers.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-zsh-launchers.json",
  "headings": [
    {
      "id": "related-working-material",
      "text": "Related working material",
      "level": 2
    },
    {
      "id": "tl-dr",
      "text": "TL;DR",
      "level": 2
    },
    {
      "id": "what-launching-an-agent-actually-costs",
      "text": "What launching an agent actually costs",
      "level": 2
    },
    {
      "id": "why-functions-not-aliases",
      "text": "Why functions, not aliases",
      "level": 2
    },
    {
      "id": "families-compound-resume-fork-and-second-accounts",
      "text": "Families compound: resume, fork, and second accounts",
      "level": 2
    },
    {
      "id": "the-prompt-builder-picks-the-agent-last",
      "text": "The prompt builder picks the agent last",
      "level": 2
    },
    {
      "id": "the-recipe-proved-on-pi",
      "text": "The recipe, proved on pi",
      "level": 2
    },
    {
      "id": "appendix",
      "text": "Appendix",
      "level": 2
    },
    {
      "id": "limits-caveats",
      "text": "Limits & caveats",
      "level": 3
    }
  ],
  "markdown": "# Thin zsh launchers and composable command families\n\nWrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable.\n\n## Related working material\n\n- [Thin zsh launchers and composable command families — prompts and exercises](/topics/factory-zsh-launchers-practice/)\n- [Thin zsh launchers and composable command families — questions and tradeoffs](/topics/factory-zsh-launchers-questions/)\n- [Thin zsh launchers and composable command families — worked example](/topics/factory-zsh-launchers-worked-example/)\n\n## TL;DR\n\n- One working set of dotfiles runs Codex, Claude Code, and pi behind two-letter functions — launch, resume, fork, and second accounts each cost two or three keystrokes.\n- You leave with four drop-in wrapper files (Codex, Claude Code, pi, and the full `pir` family) plus prompts that make your own agent build the next family for you.\n- The one move: **wrap → compose → cheat-sheet → verify with `zsh -n`**. It took five minutes to build the whole pi family live.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch 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.\n```\n\n## What launching an agent actually costs\n\nYou 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:\n\n``` text\nCODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox\n```\n\nNobody 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:\n\n``` text\n# codex.zsh — Codex behind one letter, sessions behind two.\n# Placeholders (comments only — nothing below needs editing):\n#   <personal-account> = the login that owns ~/.codex\n# Safety trade: --dangerously-bypass-approvals-and-sandbox removes approval\n# prompts. Keep it only if you accept unattended file and shell access.\n\nunalias x 2>/dev/null\nx() {\n  # Default account: <personal-account> via ~/.codex\n  CODEX_HOME=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\" \\\n    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\n# The resume/fork family: every helper routes through x, so a future fix\n# to x fixes the whole family for free.\nunalias xr xrl xrm xf 2>/dev/null\nxr()  { x resume \"$@\"; }         # pick a session to resume\nxrl() { x resume --last \"$@\"; }  # jump into the most recent session\nxrm() { x resume m \"$@\"; }       # resume the session named \"m\"\nxf()  { x fork \"$@\"; }           # fork: xf <id|name> [prompt]\n```\n\n## Why functions, not aliases\n\nAn 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:\n\n``` text\n# claude.zsh — same pattern, different agent.\n# Placeholders (comments only — nothing below needs editing):\n#   <work-account> = the login that owns ~/.claude-second\n# Safety trade: --dangerously-skip-permissions removes permission prompts.\n\nunalias clx clx2 clxw 2>/dev/null\nclx()  { claude --dangerously-skip-permissions \"$@\"; }\n\nclx2() {  # second account (<work-account>) — same UX, separate config dir\n  local config_dir=\"${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}\"\n  mkdir -p \"$config_dir\" || return\n  CLAUDE_CONFIG_DIR=\"$config_dir\" claude --dangerously-skip-permissions \"$@\"\n}\n\nclxw() {  # launch inside a named worktree: clxw <name> [args]\n  local name=\"$1\"; shift\n  CLAUDE_WORKTREE_NAME=\"$name\" claude --worktree \"$name\" --dangerously-skip-permissions \"$@\"\n}\n```\n\nFunctions 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:\n\n``` text\n# pi.zsh — wrappers absorb upstream bugs so you don't have to remember them.\n# pi's proper-lockfile dependency expects a directory at auth.json.lock; a\n# stray regular file there causes recurring ENOTDIR auth failures.\n\nunalias pi 2>/dev/null\npi() {\n  local agent_dir=\"${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}\"\n  local auth_lock=\"$agent_dir/auth.json.lock\"\n  if [[ -f \"$auth_lock\" && ! -L \"$auth_lock\" ]]; then\n    rm -f -- \"$auth_lock\"\n  fi\n  command pi \"$@\"\n}\n```\n\n## Families compound: resume, fork, and second accounts\n\nA 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`:\n\n``` text\nxfmc() {  # fork session \"m\" → compact the fork → resume it\n  local fork_id\n  fork_id=\"$(_codex_app_server_fork_compact_latest m)\" || return 1\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n# the two _codex_* helpers live elsewhere in the dotfiles — shown for shape, not for pasting\n```\n\nSecond accounts work the same way: `x2` points `CODEX_HOME` at `~/.codex-work`, 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.\n\n``` text\n$ x-\nx        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.\nx2       Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.\nxr       Resume a Codex session through the base x wrapper.\nxrl      Resume the most recent Codex session through the base x wrapper.\nxf       Run x fork; pass the conversation id/name first, then the prompt.\nxfmc     Fork conversation m, compact the fork, then resume it interactively.\np-f      Compose a prompt in p, then fork using the prompt-builder --fork-from toggle.\n# … full listing covers 35 helpers\n```\n\n## The prompt builder picks the agent last\n\nWrappers 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.\n\n``` text\n$ p target list\npi            pi     bin=pi\ncodex         codex  bin=codex  config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"\nclaude        claude bin=claude\nwork-profile       codex  bin=codex  CODEX_HOME=~/.codex-work  config=cli_auth_credentials_store=\"file\" …\nclaude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second\nclaude-third  claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third\n```\n\nYou can rehearse without launching anything: `p --print-prompt \"explain this repo\"` prints the composed prompt and exits.\n\n## The recipe, proved on pi\n\nThe 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:\n\n``` text\n$ pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n  --continue, -c        Continue previous session\n  --resume, -r          Select a session to resume\n  --fork <path|id>      Fork specific session file or partial UUID into a new session\n  --name, -n <name>     Set session display name\n  --no-session          Don't save session (ephemeral)\n```\n\nEach 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](https://sacred-ritual-w7as.here.now/#agent-guide) — 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.\n\n## Appendix\n\n### Limits & caveats\n\n- **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.\n- **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.\n- **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.\n- **\"Five minutes\" is the presenter's estimate** for the live walkthrough, not a measurement.\n- **One machine's configuration:** all evidence comes from one working set of dotfiles, version-specific snapshot. 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.\n- **Version pinning:** pi flags were captured from pi v0.80.10; re-run `--help` against your version."
}
