{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-zsh-launchers-practice",
  "slug": "zsh-launchers-practice",
  "title": "Thin zsh launchers and composable command families — prompts and exercises",
  "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families.",
  "category": "Tools",
  "tags": [
    "prompts",
    "exercises",
    "zsh-launchers"
  ],
  "sources": [
    {
      "label": "Thin zsh launchers and composable command families",
      "url": "https://sacred-ritual-w7as.here.now/"
    },
    {
      "label": "Public setup contract",
      "url": "https://sacred-ritual-w7as.here.now/agent.md"
    },
    {
      "label": "Published launcher families",
      "url": "https://sacred-ritual-w7as.here.now/agent-launchers.zsh"
    }
  ],
  "sourceUnits": [
    "02-zsh/index.html#Quick start",
    "02-zsh/index.html#Prompt library",
    "02-zsh/index.html#Set it up (agent guide)",
    "02-zsh/index.html#Attachments — take it home",
    "02-zsh/index.html#Build a wrapper family for a CLI",
    "02-zsh/index.html#Mine your shell history for wrapper candidates",
    "02-zsh/index.html#Add a second account to an existing wrapper",
    "02-zsh/index.html#Audit wrappers for flag drift after a CLI update",
    "02-zsh/agent.md",
    "02-zsh/agent-launchers.zsh"
  ],
  "collection": "factory",
  "categoryId": "tools",
  "wordCount": 3617,
  "url": "/topics/factory-zsh-launchers-practice/",
  "markdownUrl": "/markdown/factory-zsh-launchers-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-zsh-launchers-practice.json",
  "headings": [
    {
      "id": "quick-start",
      "text": "Quick start",
      "level": 2
    },
    {
      "id": "prompt-library",
      "text": "Prompt library",
      "level": 2
    },
    {
      "id": "build-a-wrapper-family-for-a-cli",
      "text": "Build a wrapper family for a CLI",
      "level": 3
    },
    {
      "id": "mine-your-shell-history-for-wrapper-candidates",
      "text": "Mine your shell history for wrapper candidates",
      "level": 3
    },
    {
      "id": "add-a-second-account-to-an-existing-wrapper",
      "text": "Add a second account to an existing wrapper",
      "level": 3
    },
    {
      "id": "audit-wrappers-for-flag-drift-after-a-cli-update",
      "text": "Audit wrappers for flag drift after a CLI update",
      "level": 3
    },
    {
      "id": "set-it-up-agent-guide",
      "text": "Set it up (agent guide)",
      "level": 2
    },
    {
      "id": "attachments-take-it-home",
      "text": "Attachments — take it home",
      "level": 2
    },
    {
      "id": "complete-reusable-setup-contract",
      "text": "Complete reusable setup contract",
      "level": 2
    },
    {
      "id": "two-letter-commands-agent-setup-guide",
      "text": "Two-Letter Commands — agent setup guide",
      "level": 2
    },
    {
      "id": "attachments-machine-fetchable",
      "text": "Attachments (machine-fetchable)",
      "level": 2
    },
    {
      "id": "prerequisites",
      "text": "Prerequisites",
      "level": 2
    },
    {
      "id": "steps",
      "text": "Steps",
      "level": 2
    },
    {
      "id": "success-check",
      "text": "Success check",
      "level": 2
    },
    {
      "id": "notes-for-agents",
      "text": "Notes for agents",
      "level": 2
    },
    {
      "id": "complete-launcher-family-attachment",
      "text": "Complete launcher-family attachment",
      "level": 2
    }
  ],
  "markdown": "# Thin zsh launchers and composable command families — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families.\n\n## Quick start\n\nSixty seconds, zero installs: build a wrapper family in a temp dir and prove it passes the right flags with a stub.\n\n``` text\ncd \"$(mktemp -d)\"\nprintf '%s\\n' 'pir() { pi --resume \"$@\"; }' 'pic() { pi --continue \"$@\"; }' \\\n  'pi-() { printf \"pir  resume\\npic  continue\\n\"; }' > pi-utils.zsh\nzsh -n pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source pi-utils.zsh; pi-; pir --check'\n```\n\n## Prompt library\n\nPaste these into your own coding agent. Each one applies the recipe without you memorizing it.\n\n### Build a wrapper family for a CLI\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: ~/.zsh-wrappers/pi-utils.zsh + passing stub test\n\n``` text\nBuild me a two-letter zsh wrapper family for the pi CLI.\n\n1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.\n2. 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`.\n3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.\n4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'\n   Expect: [stub pi] --resume --check\n5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.\n```\n\n### Mine your shell history for wrapper candidates\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a ranked top-5 list + one proposed wrapper file to review\n\n``` text\nRead 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.\n```\n\n### Add a second account to an existing wrapper\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a \\<name\\>2 wrapper + an auth-isolated second home dir\n\n``` text\nI 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.\n```\n\n### Audit wrappers for flag drift after a CLI update\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a drift report + patched wrapper files with before/after diff\n\n``` text\nMy 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.\n```\n\n## Set it up (agent guide)\n\n1.  Create `~/.zsh-wrappers/pi-utils.zsh` with exactly this content — the complete file from the live walkthrough:\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\n    unalias pir 2>/dev/null\n    pir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\n    unalias pic 2>/dev/null\n    pic() { pi --continue \"$@\"; }      # continue the most recent session\n\n    unalias pif 2>/dev/null\n    pif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\n    unalias pin 2>/dev/null\n    pin() {                            # start a named session: pin <name> [prompt]\n      local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n      pi --name \"$name\" \"$@\"\n    }\n\n    unalias pit 2>/dev/null\n    pit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n    # Recipe step 3 — every family ships its own cheat sheet (the x- convention).\n    pi-() {\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\n2.  Wire it into your shell:\n\n    ``` text\n    mkdir -p ~/.zsh-wrappers\n    # save the file above as ~/.zsh-wrappers/pi-utils.zsh, then:\n    echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc\n    exec zsh\n    ```\n\n**Success check:** syntax first, then a stub test that proves every helper passes the intended flags — 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\n``` text\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\n## Attachments — take it home\n\nBoth wrapper files discussed on this page ship with the site as downloadable attachments: [agent-launchers.zsh](https://sacred-ritual-w7as.here.now/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](https://sacred-ritual-w7as.here.now/pi-utils.zsh) (the complete `pir` walkthrough result). One block installs both:\n\n``` text\nmkdir -p ~/.zsh-wrappers\ncurl -fsSL https://sacred-ritual-w7as.here.now/agent-launchers.zsh -o ~/.zsh-wrappers/agent-launchers.zsh\ncurl -fsSL https://sacred-ritual-w7as.here.now/pi-utils.zsh -o ~/.zsh-wrappers/pi-utils.zsh\necho 'source ~/.zsh-wrappers/agent-launchers.zsh' >> ~/.zshrc\necho 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc\n```\n\nRead 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.\n\n## Complete reusable setup contract\n\n## Two-Letter Commands — agent setup guide\n\nFollowing this file sets up: a two-letter zsh wrapper family for a CLI your user runs often — base wrapper, resume/continue/fork helpers, a self-printing cheat sheet — verified with `zsh -n` and a stub test before it touches their shell config.\n\nHuman companion pages on this site (context for your user, not required for setup): `index.html` (the section guide), `replay.html` (Session Replay — the walkthrough as an annotated transcript), `dialogue.html` (Socratic Dialogue — attendee questions driving the same material).\n\n## Attachments (machine-fetchable)\n\nBoth wrapper files ship with this site as plain-text attachments you can fetch directly:\n\n- `https://sacred-ritual-w7as.here.now/pi-utils.zsh` — the complete pi wrapper family built in step 2 below (identical content; the file's \"Source it\" comment says `demo/pi-utils.zsh` because it is the verbatim workshop walkthrough result — install it at `~/.zsh-wrappers/pi-utils.zsh` regardless).\n- `https://sacred-ritual-w7as.here.now/agent-launchers.zsh` — the presenter's curated launcher families (`x`/`xr`/`xrl`/`xrm`, `x2`, `clx`/`clx2`/`clxw`, `p-f`/`p-c`, and the `x-` cheat sheet), account details generalized. NOTE: it carries `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` — show it to your user and get explicit approval before sourcing it.\n\nFetching `pi-utils.zsh` and installing it at `$HOME/.zsh-wrappers/pi-utils.zsh` is an acceptable substitute for writing the file in step 2, as long as you still run the verification in step 3.\n\nPlaceholders used below: `<cli>` = the target CLI's command name (the worked example uses `pi`); `<w>` = the family's short prefix (for `pi` the prefix is `pi`, giving `pir`, `pic`, `pif`, `pin`, `pit`). All other paths are literal.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nzsh --version\ncommand -v pi || echo \"pi not installed\"\n```\n\nExpected: zsh 5.x or newer. If `pi` is not installed, do NOT stop — pick the agent CLI your user actually runs (check `command -v codex`, `command -v claude`, or ask), use it as `<cli>`, and adapt the flag names in step 1. If no target CLI exists at all, stop and tell your user what to install.\n\n## Steps\n\n1. Capture the CLI's own session flags — never guess them:\n\n   ```bash\n   pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n   ```\n\n   Expected for pi (v0.80.10): `--resume/-r` (pick a session), `--continue/-c` (last session), `--fork <path|id>`, `--name/-n <name>`, `--no-session` (ephemeral). For a different `<cli>`, run `<cli> --help` and map its equivalents; wrap only flags that actually exist.\n\n2. Create `$HOME/.zsh-wrappers/pi-utils.zsh` with exactly this content (for a different `<cli>`, keep the identical shape — `unalias` guard before every definition, each helper one short function calling `<cli>` with one flag plus `\"$@\"`, and a `<w>-` cheat-sheet function last):\n\n   ```zsh\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\n   unalias pir 2>/dev/null\n   pir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\n   unalias pic 2>/dev/null\n   pic() { pi --continue \"$@\"; }      # continue the most recent session\n\n   unalias pif 2>/dev/null\n   pif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\n   unalias pin 2>/dev/null\n   pin() {                            # start a named session: pin <name> [prompt]\n     local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n     pi --name \"$name\" \"$@\"\n   }\n\n   unalias pit 2>/dev/null\n   pit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n   # Recipe step 3 — every family ships its own cheat sheet (the x- convention).\n   pi-() {\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\n   Create the directory first:\n\n   ```bash\n   mkdir -p \"$HOME/.zsh-wrappers\"\n   ```\n\n3. Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows `<cli>` with a function so nothing real launches:\n\n   ```bash\n   zsh -n \"$HOME/.zsh-wrappers/pi-utils.zsh\" && echo \"syntax OK\"\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source \"$HOME/.zsh-wrappers/pi-utils.zsh\"; pir --check'\n   ```\n\n4. Wire it into the shell. Ask your user before editing `~/.zshrc` if your policy requires it; otherwise append:\n\n   ```bash\n   grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' \"$HOME/.zshrc\" || \\\n     echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> \"$HOME/.zshrc\"\n   ```\n\n## Success check\n\nRun:\n\n```bash\nzsh -n \"$HOME/.zsh-wrappers/pi-utils.zsh\" && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source \"$HOME/.zsh-wrappers/pi-utils.zsh\"; pi-; pir --check'\n```\n\nExpected observable result:\n\n```\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\nThe last line proves the helper passes the intended flag. In a fresh interactive shell, `pi-` prints the cheat sheet and `pir` opens pi's session picker (only if saved sessions exist on this machine).\n\nReport to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted.\n\n## Notes for agents\n\n- **Alias collisions:** oh-my-zsh and other frameworks ship one- and two-letter aliases. Without the `unalias <name> 2>/dev/null` guard before each definition, the alias silently wins. Keep the guards even if they look redundant.\n- **Never add permission-bypass flags** (`--dangerously-bypass-approvals-and-sandbox`, `--dangerously-skip-permissions`) to a wrapper unless your user explicitly asks. They trade safety for speed.\n- **Helpers must call the command name, not an absolute path** (`pi --resume \"$@\"`, not `/some/path/pi`). That is what makes the stub test work and lets a future base-wrapper fix (like pi's `auth.json.lock` heal) apply to the whole family.\n- **Flag drift:** when the CLI updates, wrappers can break all at once. Re-run `<cli> --help` and patch only the function that owns the changed flag, then re-run the success check.\n- **pi-specific:** pi's lockfile dependency expects a directory at `~/.pi/agent/auth.json.lock`. If a stray regular (non-symlink) file appears there, pi fails auth with ENOTDIR errors; delete that file (a base `pi()` wrapper can do it before every launch).\n\n## Complete launcher-family attachment\n\nReview the permission-bypass posture and account-isolation guards before sourcing. These are examples, not a recommendation to disable approvals.\n\n```zsh\n# agent-launchers.zsh — the agent-launcher function families from the workshop.\n# Curated from the presenter's dotfiles for \"Agentic Software Factory\"\n# (the recorded snapshot), section 02: Custom zsh Functions. Adapt paths to your setup.\n# Companion page: https://sacred-ritual-w7as.here.now/\n#\n# Placeholders (comments only — nothing below needs editing to run):\n#   <personal-account> = the login that owns ~/.codex\n#   <work-account>     = the login that owns the second-account dirs\n# Lines that differ from the private originals carry an \"ADAPTED:\" comment.\n#\n# Safety trade (deliberate, visible, yours to reject):\n#   --dangerously-bypass-approvals-and-sandbox (Codex) and\n#   --dangerously-skip-permissions (Claude Code) remove approval prompts.\n#   Delete those flags if you do not accept unattended file and shell access.\n\n# ============================================================ Codex: the x family\n\n: \"${CODEX_PRIMARY_HOME:=$HOME/.codex}\"\n# ADAPTED: name the second home whatever fits your second account, e.g. ~/.codex-work\n: \"${CODEX_SECOND_HOME:=$HOME/.codex-work}\"\n\n# Names that must never be shared between accounts (auth / login only).\n# Everything else under the primary home is eligible for a symlink into x2.\n_codex_auth_local_basenames() {\n  case \"$1\" in\n    auth.json|auth.json.*|*.auth.json) return 0 ;;\n    codex-login.log|codex-login*.log) return 0 ;;\n  esac\n  return 1\n}\n\n# Build/refresh the second home as a shared view of ~/.codex, minus auth.\n# Safety rules:\n# - never write into CODEX_PRIMARY_HOME\n# - never replace a real (non-symlink) file/dir in the second home\n# - if auth.json is accidentally a symlink into primary, remove only that symlink\n# - only create/repair symlinks we manage (existing real files stay put)\n_codex_egghead_ensure_home() {\n  emulate -L zsh\n  setopt null_glob extended_glob\n\n  local primary=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\"\n  local secondary=\"${CODEX_SECOND_HOME:-$HOME/.codex-work}\"\n  local src base dest rel current\n\n  if [[ ! -d \"$primary\" ]]; then\n    print -u2 -- \"codex primary home missing: $primary\"\n    return 1\n  fi\n\n  # Refuse pathological layouts.\n  if [[ \"$secondary\" == \"$primary\" || \"$secondary\" == \"$primary\"/* ]]; then\n    print -u2 -- \"refusing second home inside primary: $secondary\"\n    return 1\n  fi\n\n  mkdir -p \"$secondary\" || return 1\n\n  # If a previous setup linked auth into the primary account, break that only.\n  dest=\"$secondary/auth.json\"\n  if [[ -L \"$dest\" ]]; then\n    current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n    case \"$current\" in\n      \"$primary/auth.json\"|\"$primary\"/auth.json)\n        rm -f \"$dest\" || return 1\n        ;;\n    esac\n  fi\n\n  # Symlink top-level primary entries except auth-local basenames.\n  for src in \"$primary\"/* \"$primary\"/.[!.]* \"$primary\"/..?*; do\n    [[ -e \"$src\" || -L \"$src\" ]] || continue\n    base=\"${src:t}\"\n    [[ \"$base\" == \".\" || \"$base\" == \"..\" ]] && continue\n    _codex_auth_local_basenames \"$base\" && continue\n\n    dest=\"$secondary/$base\"\n    if [[ -L \"$dest\" ]]; then\n      current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n      if [[ \"$current\" != \"$src\" ]]; then\n        # Only retarget an existing symlink; never touch real files.\n        ln -sfn \"$src\" \"$dest\" || return 1\n      fi\n      continue\n    fi\n    if [[ -e \"$dest\" ]]; then\n      # Real file/dir already present in the second home — leave it alone.\n      continue\n    fi\n    ln -s \"$src\" \"$dest\" || return 1\n  done\n\n  # Keep login diagnostics local even if parent `log` is shared.\n  # When primary/log is a real directory and we symlinked it, login would\n  # write into primary. Prefer a local log dir with non-auth log files linked.\n  if [[ -d \"$primary/log\" && ! -L \"$primary/log\" ]]; then\n    if [[ -L \"$secondary/log\" ]]; then\n      rm -f \"$secondary/log\" || return 1\n    fi\n    mkdir -p \"$secondary/log\" || return 1\n    for src in \"$primary/log\"/*(N) \"$primary/log\"/.[!.]*(N); do\n      [[ -e \"$src\" || -L \"$src\" ]] || continue\n      base=\"${src:t}\"\n      [[ \"$base\" == \".\" || \"$base\" == \"..\" ]] && continue\n      _codex_auth_local_basenames \"$base\" && continue\n      dest=\"$secondary/log/$base\"\n      if [[ -L \"$dest\" ]]; then\n        current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n        [[ \"$current\" == \"$src\" ]] && continue\n        ln -sfn \"$src\" \"$dest\" || return 1\n        continue\n      fi\n      [[ -e \"$dest\" ]] && continue\n      ln -s \"$src\" \"$dest\" || return 1\n    done\n  fi\n\n  # Ensure auth.json is never a symlink after ensure.\n  if [[ -L \"$secondary/auth.json\" ]]; then\n    print -u2 -- \"refusing to use symlinked auth.json in $secondary\"\n    return 1\n  fi\n\n  return 0\n}\n\nunalias x 2>/dev/null\nx() {\n  # Default account: <personal-account> via ~/.codex   (ADAPTED: email -> placeholder)\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\nunalias x2 2>/dev/null\nx2() {\n  # Secondary account: <work-account> via ~/.codex-work   (ADAPTED: email -> placeholder)\n  # Shared config/skills/sessions/etc via symlinks; local auth.json only.\n  _codex_egghead_ensure_home || return 1\n  CODEX_HOME=\"${CODEX_SECOND_HOME:-$HOME/.codex-work}\" \\\n    codex \\\n    -c 'cli_auth_credentials_store=\"file\"' \\\n    -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\n# The resume family: every helper routes through x, so a future fix\n# to x fixes the whole family for free.\nunalias xr 2>/dev/null\nxr() { x resume \"$@\"; }            # pick a session to resume\nunalias xrl 2>/dev/null\nxrl() { x resume --last \"$@\"; }    # jump into the most recent session\nunalias xrm 2>/dev/null\nxrm() { x resume m \"$@\"; }         # resume the session named \"m\" — rename to your favorite\n\n# ====================================================== Claude Code: the clx family\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# ============================================ Prompt-builder handoff: p-f and p-c\n# Requires the `p` prompt-builder CLI. Compose the prompt first; the handoff\n# hands the finished prompt to a zsh function that forks and resumes a session.\n\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.zsh-wrappers/agent-launchers.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n  # ADAPTED: sources this installed file; the original sources the presenter's\n  # full dotfiles module instead.\n}\n\n_codex_prompt_builder_fork() {\n  # ADAPTED: the private original forks through the presenter's app-server\n  # helpers, which can also compact the fork before resuming; that machinery\n  # is not portable. This version uses codex's built-in fork. --compact is\n  # accepted for interface compatibility but performs a plain fork.\n  local fork_from=\"last\"\n  while (( $# )); do\n    case \"$1\" in\n      --fork-from)\n        [[ $# -ge 2 ]] || { print -u2 -- \"missing value for --fork-from\"; return 2; }\n        fork_from=\"$2\"\n        shift 2\n        ;;\n      --compact)\n        shift\n        ;;\n      --)\n        shift\n        break\n        ;;\n      *)\n        break\n        ;;\n    esac\n  done\n  if [[ -z \"$fork_from\" || \"$fork_from\" == \"last\" ]]; then\n    x fork --last \"$@\"\n  else\n    x fork \"$fork_from\" \"$@\"\n  fi\n}\n\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ==================================== The cheat sheet: every family documents itself\n\nx-() {\n  # ADAPTED: lists only the functions in this curated file; the private\n  # original covers ~35 helpers.\n  local -a fn_name=(x x2 xr xrl xrm clx clx2 clxw p-f p-c)\n  local -A fn_desc=(\n    x    'Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.'\n    x2   'Second-account Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.'\n    xr   'Resume a Codex session through the base x wrapper.'\n    xrl  'Resume the most recent Codex session through the base x wrapper.'\n    xrm  'Resume the Codex conversation named m through the base x wrapper.'\n    clx  'Claude Code with permission prompts skipped.'\n    clx2 'Second-account Claude Code via CLAUDE_CONFIG_DIR=~/.claude-second.'\n    clxw 'Claude Code inside a named worktree: clxw <name> [args].'\n    p-f  'Compose a prompt in p, then fork the last Codex session and resume with it.'\n    p-c  'Compose a prompt in p, then fork and resume (the original also compacts).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-5s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n\n```"
}
