Shell functions, aliases, and executable boundaries: practical reference

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…

Agent Setup Prompt

Set up the zsh helper files and configuration so local agents, scripts, and non-interactive shells can reliably use the important helpers on this page.

Step 1: Inspect the helper files before changing anything.
Check these project files first:

  ls -l zsh/conf.d/40-ai.zsh zsh/conf.d/47-ai-fix.zsh zsh/codex-env.zsh 2>/dev/null || true
  ls -l zsh/tests/startup-regression.zsh 2>/dev/null || true

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

Step 2: Identify the helper names this setup needs.
Start with helpers already defined in the files above, plus any important workflow names such as:

  x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist

Adjust the list to match the actual files. Do not invent helpers that are not needed.

Step 3: Classify each helper as alias, function, builtin, hashed command, executable, or missing.
Run the quick pass:

  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
    printf '%-14s ' "$name"
    whence -w "$name" 2>/dev/null || echo MISSING
  done

Then run the detailed pass for each important helper:

  whence -w <name> 2>/dev/null || true
  type <name> 2>/dev/null || true
  alias <name> 2>/dev/null || true
  functions <name> 2>/dev/null | sed -n '1,80p'
  command -v <name> 2>/dev/null || true
  whence -p <name> 2>/dev/null || true

Locate the defining file with `funcwhere <name> 2>/dev/null || grep -RIn "<name>()\|function <name>\|alias <name>=" zsh/conf.d zsh 2>/dev/null || true`.

Step 4: Compare interactive zsh with non-interactive agent zsh.
Remember that `zsh -lc` is login, but not interactive. Check both surfaces:

  zsh -ic 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true'
  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'

Treat `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"`.

Step 5: Set up selected helper loading for `zsh -lc`.
Keep `.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 `"$@"`:

  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"

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

Step 6: Fix source guards for function files.
Function 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.

Step 7: Create executable fallbacks only for helpers that need them.
Use wrappers when CI, scripts, tmux, Prompt Builder, or another non-zsh caller must execute a helper by name without sourcing shell files.

Wrapper shape:

  mkdir -p "$HOME/.local/bin"
  cat > "$HOME/.local/bin/<name>" <<'EOF'
#!/usr/bin/env zsh
set -e
source "$HOME/.config/zsh/codex-env.zsh" >/dev/null 2>&1 || true
source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1
<name> "$@"
EOF
  chmod +x "$HOME/.local/bin/<name>"

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

Step 8: Verify PATH and wrapper resolution.
For every executable fallback:

  command -v <name>
  whence -p <name>
  test -x "$(command -v <name>)"
  zsh -lc 'p="$(command -v <name>)"; print -r -- "$p"; test -n "$p" && test -x "$p"'

If a function and executable share a name, prove both layers:

  CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name>; type <name>; whence -p <name> 2>/dev/null || true'
  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'

Step 9: Run startup regression checks.
If `zsh/tests/startup-regression.zsh` exists, run it with zsh:

  zsh zsh/tests/startup-regression.zsh

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

Step 10: Report the result.
Return a compact summary with:

  - files inspected and changed
  - each important helper name and its classification
  - defining source file for each helper
  - whether it works in `zsh -ic`, plain `zsh -lc`, and `CODEX_LOAD_ZSH_DSL=1 zsh -lc`
  - the safe `zsh -lc` handoff for each shell-only helper
  - executable wrapper paths created and their `command -v`, `whence -p`, and `test -x` results
  - startup regression result
  - any private files intentionally left untouched

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

Big Idea

Aliases save keystrokes. Functions encode workflows.

This is the handoff from Section 2:

The environment loads. Now prove what each helper name actually resolves to.

A name like xfl might be:

  • an alias
  • a zsh function
  • a shell builtin
  • a hashed command
  • an executable file on PATH
  • missing in this shell, even if it works somewhere else

This section answers the command-name question: What is this name, where is it defined, and should callers use zsh handoff or an executable fallback?

Try This Now

Pick one helper that failed in a tool, such as xfl, p-f, or fix. Run: zsh -ic 'whence -w <name>; type <name>; command -v <name> || true; whence -p <name> || true' Decide: alias/function needs zsh handoff; executable can be called directly.

Files To Inspect

Common files that define helper behavior:

zsh/conf.d/40-ai.zsh
zsh/conf.d/47-ai-fix.zsh
zsh/tests/startup-regression.zsh
zsh/codex-env.zsh

Helper names vary by setup. Classify each helper, then choose the right handoff pattern for the project.

When To Reach For This

Use this workflow when:

  • a helper works in your terminal but fails in Codex, Prompt Builder, cmux, tmux, a script, or CI
  • a helper name might be an alias or function instead of an executable
  • you want to inspect a workflow wrapper before trusting it
  • you need to decide whether a shorthand should be an alias, a function, or an executable wrapper
  • you need to expose a zsh helper safely through zsh -lc
  • you want to find where a helper is defined before editing it

Focus on command diagnosis and workflow design. Skip dotfiles that do not affect the helper you are debugging.

How This Used To Work

What you used to expect:

A helper that runs in your shell will run the same way when an agent calls it.

What the workflow gives you now:

Functions and aliases do not resolve like executables. Load shell-only helpers
with `zsh -lc 'source ...; fn "$@"'`, or create an executable wrapper when other
tools need to call them directly.

The Mental Model

Start with classification.

whence -w <name>
type <name>
alias <name> 2>/dev/null || true
functions <name> 2>/dev/null | sed -n '1,80p'
command -v <name> 2>/dev/null || true
whence -p <name> 2>/dev/null || true

Then decide the integration shape.

Result Meaning Caller Strategy
alias interactive shell shorthand use only at a prompt, or replace with function/executable
function zsh runtime command load zsh and source the defining file
builtin shell-provided command call inside the shell that owns it
hashed command cached executable path refresh lookup with rehash if stale
executable real file on PATH call directly from agents, scripts, CI, or wrappers
missing not visible in this shell find the source file or create a fallback

Safe zsh handoff shape:

zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; <name> "$@"' <name> "arg one"

Executable fallback shape:

command -v <name>
whence -p <name>
test -x "$(command -v <name>)"

Plain rule: Use zsh handoff for shell-only helpers. Use an executable wrapper when non-zsh callers need the name.

The Six Buckets

Bucket What It Is Good For Confirm With
Alias text substitution before command execution tiny shorthands and defaults alias <name>, type <name>
Function shell-defined command body arguments, branching, policy, cleanup, handoff whence -w <name>, type <name>, functions <name>
Builtin command implemented by the shell cd, alias, type, functions whence -w <name>
Hashed command cached executable path remembered by the shell faster lookup after discovery hash, rehash, whence -w <name>
Executable real file found through PATH agents, scripts, CI, subprocesses command -v <name>, whence -p <name>, test -x
Environment variable process data inherited by child processes markers, config paths, feature toggles print -r -- "$VAR"

Fast classification:

for name in alias cd git x e xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do
  printf "%-14s " "$name"
  whence -w "$name" 2>/dev/null || echo MISSING
done

Alias Or Function

Use an alias when:

  • the command is just spelling
  • there is no argument parsing
  • there is no branching
  • there is no safety policy
  • the shorthand is mainly for humans at a prompt

Example:

alias l='ls -lah'

Use a function when the helper needs:

  • arguments
  • branching
  • prerequisite checks
  • fallback behavior
  • cleanup
  • prompt construction
  • stdout/stderr discipline
  • source-control discipline
  • handoff into another tool

Example workflow helper:

fix "billing webhook double-processes paid invoice"

fix belongs as a function because it turns a terse bug report into a richer repair workflow. It is not just shorter spelling.

When An Executable Wrapper Is Required

A function is not enough when the caller needs to execute a real file.

Use a zsh handoff when:

  • the helper is local to zsh
  • the caller can run zsh -lc
  • the sourced file is small and safe
  • the helper is not needed from CI, scripts, or non-zsh tools

Use an executable wrapper when:

  • a non-zsh process must call the helper by name
  • a script must run it without sourcing shell files
  • CI must run it
  • a repo command should work for teammates
  • Prompt Builder or another tool only accepts command paths
  • the helper is important enough to survive outside one shell setup

Wrapper shape:

mkdir -p "$HOME/.local/bin"
cat > "$HOME/.local/bin/x" <<'EOF'
#!/usr/bin/env zsh
exec codex --dangerously-bypass-approvals-and-sandbox "$@"
EOF
chmod +x "$HOME/.local/bin/x"

Confirm the wrapper:

zsh -lc 'p="$(command -v x)"; print -r -- "$p"; test -n "$p" && test -x "$p"'

If both a function and executable exist, prove both layers:

CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x; type x; whence -p x 2>/dev/null || true'
env -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w x 2>/dev/null || true; command -v x || true; type x 2>/dev/null || true'

Function DSL Source Guard Trap

An exported guard is fine for env/path-only files:

[[ -n "${CODEX_AGENT_ENV_SOURCED:-}" ]] && return 0
export CODEX_AGENT_ENV_SOURCED=1

Avoid that pattern for zsh function DSL files.

Bad pattern:

[[ -n "${CODEX_ZSH_DSL_SOURCED:-}" ]] && return 0
export CODEX_ZSH_DSL_SOURCED=1

x() { codex --dangerously-bypass-approvals-and-sandbox "$@"; }

Why it fails: The exported variable can survive into a child shell even though functions and aliases do not. The child shell sees the guard, skips the source file, and the function is missing.

Use non-exported guards for shell-local function files, or make the source operation idempotent.

Discover Helpers

Use funclist as a table of contents:

funclist
funclist ai
funclist git
funclist -v x

Use funcwhere to locate the source:

funcwhere xfl
funcwhere xfc
funcwhere xport
funcwhere fix
funcwhere agent_chain
funcwhere muxai

Use funced when you are ready to inspect or edit:

funced xfl
funced xfc
funced fix

Plain rule:

funclist finds names.
funcwhere finds the file.
funced opens the definition.

If funcwhere itself is missing, classify funcwhere like any other helper.

whence -w funcwhere 2>/dev/null || true
type funcwhere 2>/dev/null || true
command -v funcwhere 2>/dev/null || true
whence -p funcwhere 2>/dev/null || true

Compare the shell surfaces only to decide where the helper is loaded:

CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'
zsh -ic 'whence -v funcwhere; whence -v x; whence -v e'

Common result:

`x` and `e` load from the agent-safe helper file.
`funcwhere` loads only from the interactive helper file.

That means the opt-in marker worked, but funcwhere is not part of the agent-safe helper set.

Choose one:

  • source the specific safe module that defines it
  • move it into a small agent-safe introspection module
  • run the inspection through zsh -ic
  • create an executable fallback when non-zsh callers need it

Confirm What A Name Really Is

Use these in order.

whence -w xfl
type xfl
alias xfl 2>/dev/null || true
functions xfl | sed -n '1,80p'
command -v xfl || true
whence -p xfl || true

If whence -w xfl says function but whence -p xfl is empty, the helper exists only as shell runtime state.

Decision after classification:

Finding Smallest Safe Move
alias only expand it into the real command or convert it to a function
function only use zsh -lc 'source ...; fn "$@"'
function plus executable decide which layer each caller should use and prove both
executable only call it directly and verify PATH order
missing in zsh -lc, present in zsh -ic source the narrow defining file or keep it interactive-only
needed by CI or scripts create an executable wrapper
depends on prompt/completion/UI state keep it interactive-only

Helper Families

Family Examples What They Represent
Codex launch/fork/export x, e, xfl, xfc, xport Codex wrapper, exec, fork, compact, transcript export
Prompt Builder handoff p-f, p-c, p-cm explicit zsh handoff around function-backed workflows
Fix workflow fix terse bug report -> richer repair workflow
Git/checkpoint helpers cfix, ghost-save, aicm workflow compression around repo state
Utility cleanup pksk, ksk alias vs function decision surface
Orchestration bridge muxai, agent_chain transition into panes, phases, and multi-agent flows

Ask The Agent This

Classify a broken helper:

`xfc` works in my terminal but fails when called by a tool.

Classify `xfc` with `whence -w`, `type`, `alias`, `functions`, `command -v`,
and `whence -p`. Find its source with `funcwhere`. Then show the smallest safe
`zsh -lc` handoff command that sources the right file and preserves arguments.

Decide alias, function, or executable:

I want a helper for replaying billing webhook tests.

Help me decide whether this should be an alias, zsh function, or executable
wrapper. The helper should accept a fixture name, run the replay command,
capture output, and print a clear pass/fail summary. Include confirmation
commands for the chosen form.

Inspect before using:

Before I use `fix` on this repo, inspect what `fix` is. Use `whence -w`, `type`,
`functions`, and `funcwhere`. Summarize what it wraps, what arguments it accepts,
what it may change, and how I should confirm the repair.

If It Goes Wrong

command not found

Run:

whence -w <name> 2>/dev/null || true
type <name> 2>/dev/null || true
alias <name> 2>/dev/null || true
functions <name> >/dev/null 2>&1 && echo function
whence -p <name> 2>/dev/null || true
command -v <name> 2>/dev/null || true

Likely result:

This helper is a function in interactive zsh, not a binary on PATH.

Recovery:

zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; <name> "$@"' <name> "arg one"

If the missing command is funcwhere, diagnose it with whence, type, and direct source-file inspection. Use whence -v funcwhere in both shell modes:

CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'
zsh -ic 'whence -v funcwhere'

If funcwhere appears only in zsh -ic, the helper lives outside the agent-safe subset. Either source its specific safe module, move it into an agent-safe introspection module, or run the inspection through zsh -ic.

Alias Fails In A Script

Aliases are shell substitutions. Use a full command, a sourced function, or an executable wrapper.

Quoting Breaks Arguments

Bad:

zsh -lc "source ~/.config/zsh/conf.d/40-ai.zsh; xfc $prompt"

Good:

zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' xfc "$prompt"

Lazy Stub Looks Like The Source

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

How To Know It Worked

You are done when:

  • you can identify what kind of helper the name resolves to
  • you know the source file
  • you know whether it is portable outside zsh
  • non-interactive callers have a safe zsh -lc handoff or executable wrapper
  • stdout/stderr behavior is safe for the caller
  • the confirmation command proves the helper can run in the intended context

References And Resources

Operational boundaries

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

Source references