Section 03
ZSH Functions / Aliases
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.
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.Workflow route
ZSH Functions / Aliases
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.

Name the software-workflow decision before launching work.
Inspect the file, command, log, prompt, or recording that proves the state.
Pick the narrow agent, tool, shell, or council path that matches the problem.
Confirm the result with output, screenshots, receipts, or saved decisions.
- Big Idea
- Try This Now
- Files To Inspect
- When To Reach For This
- How This Used To Work
- The Mental Model
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.zshHelper 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 || trueThen 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
doneAlias 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=1Avoid 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 xUse funcwhere to locate the source:
funcwhere xfl
funcwhere xfc
funcwhere xport
funcwhere fix
funcwhere agent_chain
funcwhere muxaiUse funced when you are ready to inspect or edit:
funced xfl
funced xfc
funced fixPlain 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 || trueCompare 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 || trueIf 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 || trueLikely 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 -lchandoff 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
- Helper file:
zsh/conf.d/40-ai.zsh - Fix helper source:
zsh/conf.d/47-ai-fix.zsh - Startup tests:
zsh/tests/startup-regression.zsh - Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html
- Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html
- Zsh startup files overview: https://zsh.sourceforge.io/Intro/intro_3.html
- Zsh invocation/options: https://zsh.sourceforge.io/Doc/Release/Invocation.html
- OpenAI Codex: https://openai.com/codex/