---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-zsh-launchers-practice"
title: "Thin zsh launchers and composable command families — prompts and exercises"
---

# Thin zsh launchers and composable command families — prompts and exercises

Complete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families.

## Quick start

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

``` text
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

- Agent: any coding agent
- Working directory: anywhere
- Expected result: ~/.zsh-wrappers/pi-utils.zsh + passing stub test

``` text
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

- Agent: any coding agent
- Working directory: anywhere
- Expected result: a ranked top-5 list + one proposed wrapper file to review

``` text
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

- Agent: any coding agent
- Working directory: anywhere
- Expected result: a \<name\>2 wrapper + an auth-isolated second home dir

``` text
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

- Agent: any coding agent
- Working directory: anywhere
- Expected result: a drift report + patched wrapper files with before/after diff

``` text
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)

1.  Create `~/.zsh-wrappers/pi-utils.zsh` with exactly this content — the complete file from the live walkthrough:

    ``` text
    # 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:

    ``` text
    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.

``` text
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'
```

``` text
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](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:

``` text
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.

## Complete reusable setup contract

## Two-Letter Commands — agent setup guide

Following 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.

Human 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).

## Attachments (machine-fetchable)

Both wrapper files ship with this site as plain-text attachments you can fetch directly:

- `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).
- `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.

Fetching `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.

Placeholders 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.

## Prerequisites

Check each before starting:

```bash
zsh --version
command -v pi || echo "pi not installed"
```

Expected: 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.

## Steps

1. Capture the CLI's own session flags — never guess them:

   ```bash
   pi --help | grep -E -- "--resume|--continue|--fork|--name|--no-session"
   ```

   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.

2. 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):

   ```zsh
   # 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
   }
   ```

   Create the directory first:

   ```bash
   mkdir -p "$HOME/.zsh-wrappers"
   ```

3. Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows `<cli>` with a function so nothing real launches:

   ```bash
   zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
   zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pir --check'
   ```

4. Wire it into the shell. Ask your user before editing `~/.zshrc` if your policy requires it; otherwise append:

   ```bash
   grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' "$HOME/.zshrc" || \
     echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> "$HOME/.zshrc"
   ```

## Success check

Run:

```bash
zsh -n "$HOME/.zsh-wrappers/pi-utils.zsh" && echo "syntax OK"
zsh -fc 'pi() { echo "[stub pi] $@"; }; source "$HOME/.zsh-wrappers/pi-utils.zsh"; pi-; pir --check'
```

Expected observable result:

```
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
```

The 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).

Report to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted.

## Notes for agents

- **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.
- **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.
- **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.
- **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.
- **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).

## Complete launcher-family attachment

Review the permission-bypass posture and account-isolation guards before sourcing. These are examples, not a recommendation to disable approvals.

```zsh
# agent-launchers.zsh — the agent-launcher function families from the workshop.
# Curated from the presenter's dotfiles for "Agentic Software Factory"
# (the recorded snapshot), section 02: Custom zsh Functions. Adapt paths to your setup.
# Companion page: https://sacred-ritual-w7as.here.now/
#
# Placeholders (comments only — nothing below needs editing to run):
#   <personal-account> = the login that owns ~/.codex
#   <work-account>     = the login that owns the second-account dirs
# Lines that differ from the private originals carry an "ADAPTED:" comment.
#
# Safety trade (deliberate, visible, yours to reject):
#   --dangerously-bypass-approvals-and-sandbox (Codex) and
#   --dangerously-skip-permissions (Claude Code) remove approval prompts.
#   Delete those flags if you do not accept unattended file and shell access.

# ============================================================ Codex: the x family

: "${CODEX_PRIMARY_HOME:=$HOME/.codex}"
# ADAPTED: name the second home whatever fits your second account, e.g. ~/.codex-work
: "${CODEX_SECOND_HOME:=$HOME/.codex-work}"

# Names that must never be shared between accounts (auth / login only).
# Everything else under the primary home is eligible for a symlink into x2.
_codex_auth_local_basenames() {
  case "$1" in
    auth.json|auth.json.*|*.auth.json) return 0 ;;
    codex-login.log|codex-login*.log) return 0 ;;
  esac
  return 1
}

# Build/refresh the second home as a shared view of ~/.codex, minus auth.
# Safety rules:
# - never write into CODEX_PRIMARY_HOME
# - never replace a real (non-symlink) file/dir in the second home
# - if auth.json is accidentally a symlink into primary, remove only that symlink
# - only create/repair symlinks we manage (existing real files stay put)
_codex_egghead_ensure_home() {
  emulate -L zsh
  setopt null_glob extended_glob

  local primary="${CODEX_PRIMARY_HOME:-$HOME/.codex}"
  local secondary="${CODEX_SECOND_HOME:-$HOME/.codex-work}"
  local src base dest rel current

  if [[ ! -d "$primary" ]]; then
    print -u2 -- "codex primary home missing: $primary"
    return 1
  fi

  # Refuse pathological layouts.
  if [[ "$secondary" == "$primary" || "$secondary" == "$primary"/* ]]; then
    print -u2 -- "refusing second home inside primary: $secondary"
    return 1
  fi

  mkdir -p "$secondary" || return 1

  # If a previous setup linked auth into the primary account, break that only.
  dest="$secondary/auth.json"
  if [[ -L "$dest" ]]; then
    current="$(readlink "$dest" 2>/dev/null || true)"
    case "$current" in
      "$primary/auth.json"|"$primary"/auth.json)
        rm -f "$dest" || return 1
        ;;
    esac
  fi

  # Symlink top-level primary entries except auth-local basenames.
  for src in "$primary"/* "$primary"/.[!.]* "$primary"/..?*; do
    [[ -e "$src" || -L "$src" ]] || continue
    base="${src:t}"
    [[ "$base" == "." || "$base" == ".." ]] && continue
    _codex_auth_local_basenames "$base" && continue

    dest="$secondary/$base"
    if [[ -L "$dest" ]]; then
      current="$(readlink "$dest" 2>/dev/null || true)"
      if [[ "$current" != "$src" ]]; then
        # Only retarget an existing symlink; never touch real files.
        ln -sfn "$src" "$dest" || return 1
      fi
      continue
    fi
    if [[ -e "$dest" ]]; then
      # Real file/dir already present in the second home — leave it alone.
      continue
    fi
    ln -s "$src" "$dest" || return 1
  done

  # Keep login diagnostics local even if parent `log` is shared.
  # When primary/log is a real directory and we symlinked it, login would
  # write into primary. Prefer a local log dir with non-auth log files linked.
  if [[ -d "$primary/log" && ! -L "$primary/log" ]]; then
    if [[ -L "$secondary/log" ]]; then
      rm -f "$secondary/log" || return 1
    fi
    mkdir -p "$secondary/log" || return 1
    for src in "$primary/log"/*(N) "$primary/log"/.[!.]*(N); do
      [[ -e "$src" || -L "$src" ]] || continue
      base="${src:t}"
      [[ "$base" == "." || "$base" == ".." ]] && continue
      _codex_auth_local_basenames "$base" && continue
      dest="$secondary/log/$base"
      if [[ -L "$dest" ]]; then
        current="$(readlink "$dest" 2>/dev/null || true)"
        [[ "$current" == "$src" ]] && continue
        ln -sfn "$src" "$dest" || return 1
        continue
      fi
      [[ -e "$dest" ]] && continue
      ln -s "$src" "$dest" || return 1
    done
  fi

  # Ensure auth.json is never a symlink after ensure.
  if [[ -L "$secondary/auth.json" ]]; then
    print -u2 -- "refusing to use symlinked auth.json in $secondary"
    return 1
  fi

  return 0
}

unalias x 2>/dev/null
x() {
  # Default account: <personal-account> via ~/.codex   (ADAPTED: email -> placeholder)
  CODEX_HOME="${CODEX_PRIMARY_HOME:-$HOME/.codex}" \
    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
    --dangerously-bypass-approvals-and-sandbox "$@"
}

unalias x2 2>/dev/null
x2() {
  # Secondary account: <work-account> via ~/.codex-work   (ADAPTED: email -> placeholder)
  # Shared config/skills/sessions/etc via symlinks; local auth.json only.
  _codex_egghead_ensure_home || return 1
  CODEX_HOME="${CODEX_SECOND_HOME:-$HOME/.codex-work}" \
    codex \
    -c 'cli_auth_credentials_store="file"' \
    -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
    --dangerously-bypass-approvals-and-sandbox "$@"
}

# The resume family: every helper routes through x, so a future fix
# to x fixes the whole family for free.
unalias xr 2>/dev/null
xr() { x resume "$@"; }            # pick a session to resume
unalias xrl 2>/dev/null
xrl() { x resume --last "$@"; }    # jump into the most recent session
unalias xrm 2>/dev/null
xrm() { x resume m "$@"; }         # resume the session named "m" — rename to your favorite

# ====================================================== Claude Code: the clx family

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 "$@"
}

# ============================================ Prompt-builder handoff: p-f and p-c
# Requires the `p` prompt-builder CLI. Compose the prompt first; the handoff
# hands the finished prompt to a zsh function that forks and resumes a session.

_p_handoff_zsh() {
  local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
  shift
  p \
    --handoff-command zsh \
    --handoff-arg -lc \
    --handoff-arg "source \"\$HOME/.zsh-wrappers/agent-launchers.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
    --handoff-arg "$fn" \
    "$@"
  # ADAPTED: sources this installed file; the original sources the presenter's
  # full dotfiles module instead.
}

_codex_prompt_builder_fork() {
  # ADAPTED: the private original forks through the presenter's app-server
  # helpers, which can also compact the fork before resuming; that machinery
  # is not portable. This version uses codex's built-in fork. --compact is
  # accepted for interface compatibility but performs a plain fork.
  local fork_from="last"
  while (( $# )); do
    case "$1" in
      --fork-from)
        [[ $# -ge 2 ]] || { print -u2 -- "missing value for --fork-from"; return 2; }
        fork_from="$2"
        shift 2
        ;;
      --compact)
        shift
        ;;
      --)
        shift
        break
        ;;
      *)
        break
        ;;
    esac
  done
  if [[ -z "$fork_from" || "$fork_from" == "last" ]]; then
    x fork --last "$@"
  else
    x fork "$fork_from" "$@"
  fi
}

p-f() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}
p-c() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}

# ==================================== The cheat sheet: every family documents itself

x-() {
  # ADAPTED: lists only the functions in this curated file; the private
  # original covers ~35 helpers.
  local -a fn_name=(x x2 xr xrl xrm clx clx2 clxw p-f p-c)
  local -A fn_desc=(
    x    'Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.'
    x2   'Second-account 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.'
    xrm  'Resume the Codex conversation named m through the base x wrapper.'
    clx  'Claude Code with permission prompts skipped.'
    clx2 'Second-account Claude Code via CLAUDE_CONFIG_DIR=~/.claude-second.'
    clxw 'Claude Code inside a named worktree: clxw <name> [args].'
    p-f  'Compose a prompt in p, then fork the last Codex session and resume with it.'
    p-c  'Compose a prompt in p, then fork and resume (the original also compacts).'
  )
  local fn
  for fn in "${fn_name[@]}"; do
    printf '%-5s %s\n' "$fn" "${fn_desc[$fn]}"
  done
}

```

## Original references

- [Thin zsh launchers and composable command families](https://sacred-ritual-w7as.here.now/)
- [Public setup contract](https://sacred-ritual-w7as.here.now/agent.md)
- [Published launcher families](https://sacred-ritual-w7as.here.now/agent-launchers.zsh)
