{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-functions-reference",
  "slug": "shell-functions-reference",
  "title": "Shell functions, aliases, and executable boundaries: practical reference",
  "summary": "Zsh helper diagnosis and agent integration reference covering a ten-step setup prompt, command classification, alias/function/executable design, interactive versus login-shell loading, argument-safe handoffs, executable wrappers, source guards, helper…",
  "category": "Tools",
  "tags": [
    "zsh",
    "helpers",
    "cli"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/The Mental Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/The Six Buckets",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Alias Or Function",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/When An Executable Wrapper Is Required",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Function DSL Source Guard Trap",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Discover Helpers",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Confirm What A Name Really Is",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Helper Families",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/`command not found`",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Alias Fails In A Script",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Quoting Breaks Arguments",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Lazy Stub Looks Like The Source",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 3080,
  "url": "/topics/codex-shell-functions-reference/",
  "markdownUrl": "/markdown/codex-shell-functions-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-functions-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "the-mental-model",
      "text": "The Mental Model",
      "level": 2
    },
    {
      "id": "the-six-buckets",
      "text": "The Six Buckets",
      "level": 2
    },
    {
      "id": "alias-or-function",
      "text": "Alias Or Function",
      "level": 2
    },
    {
      "id": "when-an-executable-wrapper-is-required",
      "text": "When An Executable Wrapper Is Required",
      "level": 2
    },
    {
      "id": "function-dsl-source-guard-trap",
      "text": "Function DSL Source Guard Trap",
      "level": 2
    },
    {
      "id": "discover-helpers",
      "text": "Discover Helpers",
      "level": 2
    },
    {
      "id": "confirm-what-a-name-really-is",
      "text": "Confirm What A Name Really Is",
      "level": 2
    },
    {
      "id": "helper-families",
      "text": "Helper Families",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "command-not-found",
      "text": "`command not found`",
      "level": 3
    },
    {
      "id": "alias-fails-in-a-script",
      "text": "Alias Fails In A Script",
      "level": 3
    },
    {
      "id": "quoting-breaks-arguments",
      "text": "Quoting Breaks Arguments",
      "level": 3
    },
    {
      "id": "lazy-stub-looks-like-the-source",
      "text": "Lazy Stub Looks Like The Source",
      "level": 3
    },
    {
      "id": "how-to-know-it-worked",
      "text": "How To Know It Worked",
      "level": 2
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Shell functions, aliases, and executable boundaries: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the zsh helper files and configuration so local agents, scripts, and non-interactive shells can reliably use the important helpers on this page.\n\nStep 1: Inspect the helper files before changing anything.\nCheck these project files first:\n\n  ls -l zsh/conf.d/40-ai.zsh zsh/conf.d/47-ai-fix.zsh zsh/codex-env.zsh 2>/dev/null || true\n  ls -l zsh/tests/startup-regression.zsh 2>/dev/null || true\n\nUse `zsh/conf.d/40-ai.zsh` for small agent-safe helper definitions, `zsh/conf.d/47-ai-fix.zsh` for the fix workflow, and `zsh/codex-env.zsh` for safe PATH/env setup. If a required file is missing, create the smallest file needed from public examples in this package. Do not copy private local config, secret helper files, full Codex config, token/API-key wiring, cookies, private endpoints, or raw `env` output.\n\nStep 2: Identify the helper names this setup needs.\nStart with helpers already defined in the files above, plus any important workflow names such as:\n\n  x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist\n\nAdjust the list to match the actual files. Do not invent helpers that are not needed.\n\nStep 3: Classify each helper as alias, function, builtin, hashed command, executable, or missing.\nRun the quick pass:\n\n  for name in x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist; do\n    printf '%-14s ' \"$name\"\n    whence -w \"$name\" 2>/dev/null || echo MISSING\n  done\n\nThen run the detailed pass for each important helper:\n\n  whence -w <name> 2>/dev/null || true\n  type <name> 2>/dev/null || true\n  alias <name> 2>/dev/null || true\n  functions <name> 2>/dev/null | sed -n '1,80p'\n  command -v <name> 2>/dev/null || true\n  whence -p <name> 2>/dev/null || true\n\nLocate the defining file with `funcwhere <name> 2>/dev/null || grep -RIn \"<name>()\\|function <name>\\|alias <name>=\" zsh/conf.d zsh 2>/dev/null || true`.\n\nStep 4: Compare interactive zsh with non-interactive agent zsh.\nRemember that `zsh -lc` is login, but not interactive. Check both surfaces:\n\n  zsh -ic 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true'\n  CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; whence -p <name> 2>/dev/null || true'\n\nTreat `CODEX_LOAD_ZSH_DSL` as a local opt-in marker, not a built-in Codex feature. If Codex should provide it, configure the launch path with `shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"`.\n\nStep 5: Set up selected helper loading for `zsh -lc`.\nKeep `.zshrc`-only behavior out of the required agent path. Source only the narrow files needed for the helper. For shell-only helpers, use this handoff shape and preserve arguments through `\"$@\"`:\n\n  zsh -lc 'source \"$PWD/zsh/codex-env.zsh\" >/dev/null 2>&1; source \"$PWD/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n\nIf the installed source path is different, replace the source path with the inspected file path. Do not interpolate user input inside the single-quoted `zsh -lc` body.\n\nStep 6: Fix source guards for function files.\nFunction and alias files must not use exported source guards that child shells inherit while losing the functions. If a function DSL file uses an exported guard, replace it with a non-exported guard or make the file safe to source repeatedly. Env/path-only files may use exported guards when appropriate.\n\nStep 7: Create executable fallbacks only for helpers that need them.\nUse wrappers when CI, scripts, tmux, Prompt Builder, or another non-zsh caller must execute a helper by name without sourcing shell files.\n\nWrapper shape:\n\n  mkdir -p \"$HOME/.local/bin\"\n  cat > \"$HOME/.local/bin/<name>\" <<'EOF'\n#!/usr/bin/env zsh\nset -e\nsource \"$HOME/.config/zsh/codex-env.zsh\" >/dev/null 2>&1 || true\nsource \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1\n<name> \"$@\"\nEOF\n  chmod +x \"$HOME/.local/bin/<name>\"\n\nAdjust source paths to the real installed helper files. If the wrapper can call a real binary directly, use `exec /path/to/binary \"$@\"` instead. Avoid wrapper recursion: prove the wrapper calls the intended function or executable.\n\nStep 8: Verify PATH and wrapper resolution.\nFor every executable fallback:\n\n  command -v <name>\n  whence -p <name>\n  test -x \"$(command -v <name>)\"\n  zsh -lc 'p=\"$(command -v <name>)\"; print -r -- \"$p\"; test -n \"$p\" && test -x \"$p\"'\n\nIf a function and executable share a name, prove both layers:\n\n  CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name>; type <name>; whence -p <name> 2>/dev/null || true'\n  env -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; type <name> 2>/dev/null || true'\n\nStep 9: Run startup regression checks.\nIf `zsh/tests/startup-regression.zsh` exists, run it with zsh:\n\n  zsh zsh/tests/startup-regression.zsh\n\nIf it does not exist, add a focused check that verifies the selected helper files load quietly, expected helpers resolve, PATH order is stable, and missing helpers fail clearly.\n\nStep 10: Report the result.\nReturn a compact summary with:\n\n  - files inspected and changed\n  - each important helper name and its classification\n  - defining source file for each helper\n  - whether it works in `zsh -ic`, plain `zsh -lc`, and `CODEX_LOAD_ZSH_DSL=1 zsh -lc`\n  - the safe `zsh -lc` handoff for each shell-only helper\n  - executable wrapper paths created and their `command -v`, `whence -p`, and `test -x` results\n  - startup regression result\n  - any private files intentionally left untouched\n\nDo not print secrets, raw environment dumps, tokens, cookies, API keys, or private endpoints. If a helper cannot be safely set up, stop at the smallest clear blocker and report the next action.\n```\n\n## Big Idea\n\nAliases save keystrokes. Functions encode workflows.\n\nThis is the handoff from Section 2:\n\n```text\nThe environment loads. Now prove what each helper name actually resolves to.\n```\n\nA name like `xfl` might be:\n\n- an alias\n- a zsh function\n- a shell builtin\n- a hashed command\n- an executable file on PATH\n- missing in this shell, even if it works somewhere else\n\nThis section answers the command-name question: What is this name, where is it defined, and should callers use zsh handoff or an executable fallback?\n\n## Try This Now\n\nPick one helper that failed in a tool, such as `xfl`, `p-f`, or `fix`.\nRun: `zsh -ic 'whence -w <name>; type <name>; command -v <name> || true; whence -p <name> || true'`\nDecide: alias/function needs zsh handoff; executable can be called directly.\n\n## Files To Inspect\n\nCommon files that define helper behavior:\n\n```text\nzsh/conf.d/40-ai.zsh\nzsh/conf.d/47-ai-fix.zsh\nzsh/tests/startup-regression.zsh\nzsh/codex-env.zsh\n```\n\nHelper names vary by setup. Classify each helper, then choose the right handoff pattern for the project.\n\n## When To Reach For This\n\nUse this workflow when:\n\n- a helper works in your terminal but fails in Codex, Prompt Builder, cmux, tmux, a script, or CI\n- a helper name might be an alias or function instead of an executable\n- you want to inspect a workflow wrapper before trusting it\n- you need to decide whether a shorthand should be an alias, a function, or an executable wrapper\n- you need to expose a zsh helper safely through `zsh -lc`\n- you want to find where a helper is defined before editing it\n\nFocus on command diagnosis and workflow design. Skip dotfiles that do not affect the helper you are debugging.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nA helper that runs in your shell will run the same way when an agent calls it.\n```\n\nWhat the workflow gives you now:\n\n```text\nFunctions and aliases do not resolve like executables. Load shell-only helpers\nwith `zsh -lc 'source ...; fn \"$@\"'`, or create an executable wrapper when other\ntools need to call them directly.\n```\n\n## The Mental Model\n\nStart with classification.\n\n```zsh\nwhence -w <name>\ntype <name>\nalias <name> 2>/dev/null || true\nfunctions <name> 2>/dev/null | sed -n '1,80p'\ncommand -v <name> 2>/dev/null || true\nwhence -p <name> 2>/dev/null || true\n```\n\nThen decide the integration shape.\n\n| Result | Meaning | Caller Strategy |\n| --- | --- | --- |\n| alias | interactive shell shorthand | use only at a prompt, or replace with function/executable |\n| function | zsh runtime command | load zsh and source the defining file |\n| builtin | shell-provided command | call inside the shell that owns it |\n| hashed command | cached executable path | refresh lookup with `rehash` if stale |\n| executable | real file on PATH | call directly from agents, scripts, CI, or wrappers |\n| missing | not visible in this shell | find the source file or create a fallback |\n\nSafe zsh handoff shape:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n```\n\nExecutable fallback shape:\n\n```zsh\ncommand -v <name>\nwhence -p <name>\ntest -x \"$(command -v <name>)\"\n```\n\nPlain rule: Use zsh handoff for shell-only helpers. Use an executable wrapper when non-zsh callers need the name.\n\n## The Six Buckets\n\n| Bucket | What It Is | Good For | Confirm With |\n| --- | --- | --- | --- |\n| Alias | text substitution before command execution | tiny shorthands and defaults | `alias <name>`, `type <name>` |\n| Function | shell-defined command body | arguments, branching, policy, cleanup, handoff | `whence -w <name>`, `type <name>`, `functions <name>` |\n| Builtin | command implemented by the shell | `cd`, `alias`, `type`, `functions` | `whence -w <name>` |\n| Hashed command | cached executable path remembered by the shell | faster lookup after discovery | `hash`, `rehash`, `whence -w <name>` |\n| Executable | real file found through PATH | agents, scripts, CI, subprocesses | `command -v <name>`, `whence -p <name>`, `test -x` |\n| Environment variable | process data inherited by child processes | markers, config paths, feature toggles | `print -r -- \"$VAR\"` |\n\nFast classification:\n\n```zsh\nfor name in alias cd git x e xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do\n  printf \"%-14s \" \"$name\"\n  whence -w \"$name\" 2>/dev/null || echo MISSING\ndone\n```\n\n## Alias Or Function\n\nUse an alias when:\n\n- the command is just spelling\n- there is no argument parsing\n- there is no branching\n- there is no safety policy\n- the shorthand is mainly for humans at a prompt\n\nExample:\n\n```zsh\nalias l='ls -lah'\n```\n\nUse a function when the helper needs:\n\n- arguments\n- branching\n- prerequisite checks\n- fallback behavior\n- cleanup\n- prompt construction\n- stdout/stderr discipline\n- source-control discipline\n- handoff into another tool\n\nExample workflow helper:\n\n```zsh\nfix \"billing webhook double-processes paid invoice\"\n```\n\n`fix` belongs as a function because it turns a terse bug report into a richer repair workflow. It is not just shorter spelling.\n\n## When An Executable Wrapper Is Required\n\nA function is not enough when the caller needs to execute a real file.\n\nUse a zsh handoff when:\n\n- the helper is local to zsh\n- the caller can run `zsh -lc`\n- the sourced file is small and safe\n- the helper is not needed from CI, scripts, or non-zsh tools\n\nUse an executable wrapper when:\n\n- a non-zsh process must call the helper by name\n- a script must run it without sourcing shell files\n- CI must run it\n- a repo command should work for teammates\n- Prompt Builder or another tool only accepts command paths\n- the helper is important enough to survive outside one shell setup\n\nWrapper shape:\n\n```zsh\nmkdir -p \"$HOME/.local/bin\"\ncat > \"$HOME/.local/bin/x\" <<'EOF'\n#!/usr/bin/env zsh\nexec codex --dangerously-bypass-approvals-and-sandbox \"$@\"\nEOF\nchmod +x \"$HOME/.local/bin/x\"\n```\n\nConfirm the wrapper:\n\n```zsh\nzsh -lc 'p=\"$(command -v x)\"; print -r -- \"$p\"; test -n \"$p\" && test -x \"$p\"'\n```\n\nIf both a function and executable exist, prove both layers:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x; type x; whence -p x 2>/dev/null || true'\nenv -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w x 2>/dev/null || true; command -v x || true; type x 2>/dev/null || true'\n```\n\n## Function DSL Source Guard Trap\n\nAn exported guard is fine for env/path-only files:\n\n```zsh\n[[ -n \"${CODEX_AGENT_ENV_SOURCED:-}\" ]] && return 0\nexport CODEX_AGENT_ENV_SOURCED=1\n```\n\nAvoid that pattern for zsh function DSL files.\n\nBad pattern:\n\n```zsh\n[[ -n \"${CODEX_ZSH_DSL_SOURCED:-}\" ]] && return 0\nexport CODEX_ZSH_DSL_SOURCED=1\n\nx() { codex --dangerously-bypass-approvals-and-sandbox \"$@\"; }\n```\n\nWhy it fails: The exported variable can survive into a child shell even though functions and aliases do not.\nThe child shell sees the guard, skips the source file, and the function is missing.\n\nUse non-exported guards for shell-local function files, or make the source operation idempotent.\n\n## Discover Helpers\n\nUse `funclist` as a table of contents:\n\n```zsh\nfunclist\nfunclist ai\nfunclist git\nfunclist -v x\n```\n\nUse `funcwhere` to locate the source:\n\n```zsh\nfuncwhere xfl\nfuncwhere xfc\nfuncwhere xport\nfuncwhere fix\nfuncwhere agent_chain\nfuncwhere muxai\n```\n\nUse `funced` when you are ready to inspect or edit:\n\n```zsh\nfunced xfl\nfunced xfc\nfunced fix\n```\n\nPlain rule:\n\n```text\nfunclist finds names.\nfuncwhere finds the file.\nfunced opens the definition.\n```\n\nIf `funcwhere` itself is missing, classify `funcwhere` like any other helper.\n\n```zsh\nwhence -w funcwhere 2>/dev/null || true\ntype funcwhere 2>/dev/null || true\ncommand -v funcwhere 2>/dev/null || true\nwhence -p funcwhere 2>/dev/null || true\n```\n\nCompare the shell surfaces only to decide where the helper is loaded:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'\nzsh -ic 'whence -v funcwhere; whence -v x; whence -v e'\n```\n\nCommon result:\n\n```text\n`x` and `e` load from the agent-safe helper file.\n`funcwhere` loads only from the interactive helper file.\n```\n\nThat means the opt-in marker worked, but `funcwhere` is not part of the agent-safe helper set.\n\nChoose one:\n\n- source the specific safe module that defines it\n- move it into a small agent-safe introspection module\n- run the inspection through `zsh -ic`\n- create an executable fallback when non-zsh callers need it\n\n## Confirm What A Name Really Is\n\nUse these in order.\n\n```zsh\nwhence -w xfl\ntype xfl\nalias xfl 2>/dev/null || true\nfunctions xfl | sed -n '1,80p'\ncommand -v xfl || true\nwhence -p xfl || true\n```\n\nIf `whence -w xfl` says `function` but `whence -p xfl` is empty, the helper exists only as shell runtime state.\n\nDecision after classification:\n\n| Finding | Smallest Safe Move |\n| --- | --- |\n| alias only | expand it into the real command or convert it to a function |\n| function only | use `zsh -lc 'source ...; fn \"$@\"'` |\n| function plus executable | decide which layer each caller should use and prove both |\n| executable only | call it directly and verify PATH order |\n| missing in `zsh -lc`, present in `zsh -ic` | source the narrow defining file or keep it interactive-only |\n| needed by CI or scripts | create an executable wrapper |\n| depends on prompt/completion/UI state | keep it interactive-only |\n\n## Helper Families\n\n| Family | Examples | What They Represent |\n| --- | --- | --- |\n| Codex launch/fork/export | `x`, `e`, `xfl`, `xfc`, `xport` | Codex wrapper, exec, fork, compact, transcript export |\n| Prompt Builder handoff | `p-f`, `p-c`, `p-cm` | explicit zsh handoff around function-backed workflows |\n| Fix workflow | `fix` | terse bug report -> richer repair workflow |\n| Git/checkpoint helpers | `cfix`, `ghost-save`, `aicm` | workflow compression around repo state |\n| Utility cleanup | `pksk`, `ksk` | alias vs function decision surface |\n| Orchestration bridge | `muxai`, `agent_chain` | transition into panes, phases, and multi-agent flows |\n\n## Ask The Agent This\n\nClassify a broken helper:\n\n```text\n`xfc` works in my terminal but fails when called by a tool.\n\nClassify `xfc` with `whence -w`, `type`, `alias`, `functions`, `command -v`,\nand `whence -p`. Find its source with `funcwhere`. Then show the smallest safe\n`zsh -lc` handoff command that sources the right file and preserves arguments.\n```\n\nDecide alias, function, or executable:\n\n```text\nI want a helper for replaying billing webhook tests.\n\nHelp me decide whether this should be an alias, zsh function, or executable\nwrapper. The helper should accept a fixture name, run the replay command,\ncapture output, and print a clear pass/fail summary. Include confirmation\ncommands for the chosen form.\n```\n\nInspect before using:\n\n```text\nBefore I use `fix` on this repo, inspect what `fix` is. Use `whence -w`, `type`,\n`functions`, and `funcwhere`. Summarize what it wraps, what arguments it accepts,\nwhat it may change, and how I should confirm the repair.\n```\n\n## If It Goes Wrong\n\n### `command not found`\n\nRun:\n\n```zsh\nwhence -w <name> 2>/dev/null || true\ntype <name> 2>/dev/null || true\nalias <name> 2>/dev/null || true\nfunctions <name> >/dev/null 2>&1 && echo function\nwhence -p <name> 2>/dev/null || true\ncommand -v <name> 2>/dev/null || true\n```\n\nLikely result:\n\n```text\nThis helper is a function in interactive zsh, not a binary on PATH.\n```\n\nRecovery:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n```\n\nIf the missing command is `funcwhere`, diagnose it with `whence`, `type`, and direct source-file inspection.\nUse `whence -v funcwhere` in both shell modes:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'\nzsh -ic 'whence -v funcwhere'\n```\n\nIf `funcwhere` appears only in `zsh -ic`, the helper lives outside the\nagent-safe subset. Either source its specific safe module, move it into an\nagent-safe introspection module, or run the inspection through `zsh -ic`.\n\n### Alias Fails In A Script\n\nAliases are shell substitutions. Use a full command, a sourced function, or an executable wrapper.\n\n### Quoting Breaks Arguments\n\nBad:\n\n```zsh\nzsh -lc \"source ~/.config/zsh/conf.d/40-ai.zsh; xfc $prompt\"\n```\n\nGood:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' xfc \"$prompt\"\n```\n\n### Lazy Stub Looks Like The Source\n\nIf `funcwhere fix` points at a lazy stub file, that is not automatically a failure. It often means the helper is discoverable before the full module loads.\n\n## How To Know It Worked\n\nYou are done when:\n\n- you can identify what kind of helper the name resolves to\n- you know the source file\n- you know whether it is portable outside zsh\n- non-interactive callers have a safe `zsh -lc` handoff or executable wrapper\n- stdout/stderr behavior is safe for the caller\n- the confirmation command proves the helper can run in the intended context\n\n## References And Resources\n\n- Helper file: `zsh/conf.d/40-ai.zsh`\n- Fix helper source: `zsh/conf.d/47-ai-fix.zsh`\n- Startup tests: `zsh/tests/startup-regression.zsh`\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n- Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html\n- Zsh startup files overview: https://zsh.sourceforge.io/Intro/intro_3.html\n- Zsh invocation/options: https://zsh.sourceforge.io/Doc/Release/Invocation.html\n- OpenAI Codex: https://openai.com/codex/\n\n## Operational boundaries\n\n- Shell helper examples that bypass approvals and sandboxing require a trusted, separately isolated environment. Generic executable wrappers are the portability boundary; shell-function presence alone is not a smoke test.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
