{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-zsh-launchers-questions",
  "slug": "zsh-launchers-questions",
  "title": "Thin zsh launchers and composable command families — questions and tradeoffs",
  "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Tools",
  "tags": [
    "zsh-launchers",
    "questions"
  ],
  "sources": [
    {
      "label": "Thin zsh launchers and composable command families — questions and tradeoffs",
      "url": "https://sacred-ritual-w7as.here.now/dialogue.html"
    }
  ],
  "sourceUnits": [
    "02-zsh/dialogue.html#The room asks"
  ],
  "collection": "factory",
  "categoryId": "tools",
  "wordCount": 1212,
  "url": "/topics/factory-zsh-launchers-questions/",
  "markdownUrl": "/markdown/factory-zsh-launchers-questions.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-zsh-launchers-questions.json",
  "headings": [
    {
      "id": "the-room-asks",
      "text": "The room asks",
      "level": 2
    }
  ],
  "markdown": "# Thin zsh launchers and composable command families — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The room asks\n\nWhy not just aliases?\n\nAn 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:\n\n``` text\nCODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox\n```\n\nAnd once `x` owns that, the entire resume family is one-line compositions on top of it:\n\n``` text\nxr()  { x resume \"$@\"; }         # pick a session to resume\nxrl() { x resume --last \"$@\"; }  # jump into the most recent session\n```\n\nOkay, but I run two Codex accounts. Doesn't this fall apart the moment auth is involved?\n\nThat's what `x2` is: the same wrapper pointed at a second home directory (`CODEX_HOME=~/.codex-work`) 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:\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\nIsn't `--dangerously-bypass-approvals-and-sandbox` terrifying?\n\nIt 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.\n\nHow do you remember fifteen two-letter functions?\n\nI 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:\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\nThe CLI updates and renames a flag. Now every wrapper is broken at once, right?\n\nYes — 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:\n\n``` text\nzsh -n ~/.zsh-wrappers/pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'\n```\n\nRe-run `--help`, patch the one function that owns the changed flag, re-run the stub. The [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library has a drift-audit prompt that makes your agent do the whole pass.\n\nYou keep saying you \"pick the agent last.\" What does that actually mean?\n\nWrappers 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.\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\nHelpers 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.\n\nA new agent CLI ships next month. How long before it feels like this?\n\nAbout 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:\n\n``` text\n# pi-utils.zsh — the \"pir\" walkthrough result\n# Built live at the workshop following the same recipe as the x/xr family.\n# Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n# Recipe step 0 — the base wrapper already exists in the dotfiles\n# (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n# pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n# Recipe step 1 — read the CLI's own session flags:\n#   pi --help | grep -E \"resume|continue|fork|name\"\n#   --continue, -c   Continue previous session\n#   --resume, -r     Select a session to resume\n#   --fork <path|id> Fork a session into a new session\n#   --name, -n       Set session display name\n\n# Recipe step 2 — wrap each flag as a two/three-letter function.\n\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n\nunalias pit 2>/dev/null\npit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n# Recipe step 3 — every family ships its own cheat sheet (the x- convention).\npi-() {\n  local -a fn_name=(pi pir pic pif pin pit)\n  local -A fn_desc=(\n    pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n    pir 'Resume: open the session picker (pi --resume).'\n    pic 'Continue: jump straight back into the last session (pi --continue).'\n    pif 'Fork a session into a new one: pif <path|id> [prompt].'\n    pin 'Start a named session: pin <name> [prompt].'\n    pit 'Throwaway: run without saving a session (pi --no-session).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n```\n\nWant to watch that file get built prompt by prompt? That's the [Session Replay](https://sacred-ritual-w7as.here.now/replay.html) page. Both this file and the full launcher family (`agent-launchers.zsh`) are downloadable attachments — grab the install block on the [section guide](https://sacred-ritual-w7as.here.now/index.html).\n\nEvery 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](https://sacred-ritual-w7as.here.now/index.html) appendix."
}
