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.


setup agent 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.

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.

Eggo separates each command form into the correct bucket for the ZSH Functions / Aliases workflow, making the page's operating move visible.
Intent

Name the software-workflow decision before launching work.

Evidence

Inspect the file, command, log, prompt, or recording that proves the state.

Route

Pick the narrow agent, tool, shell, or council path that matches the problem.

Verify

Confirm the result with output, screenshots, receipts, or saved decisions.

  1. Big Idea
  2. Try This Now
  3. Files To Inspect
  4. When To Reach For This
  5. How This Used To Work
  6. The Mental Model
the executable fallback is isolated as the reliable route

Big Idea

Aliases save keystrokes. Functions encode workflows.

This is the handoff from Section 2:

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

A name like xfl might be:

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:

snippet-2
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:

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:

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

What the workflow gives you now:

snippet-4
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.

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

ResultMeaningCaller Strategy
aliasinteractive shell shorthanduse only at a prompt, or replace with function/executable
functionzsh runtime commandload zsh and source the defining file
builtinshell-provided commandcall inside the shell that owns it
hashed commandcached executable pathrefresh lookup with rehash if stale
executablereal file on PATHcall directly from agents, scripts, CI, or wrappers
missingnot visible in this shellfind the source file or create a fallback

Safe zsh handoff shape:

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

Executable fallback shape:

zsh
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

BucketWhat It IsGood ForConfirm With
Aliastext substitution before command executiontiny shorthands and defaultsalias <name>, type <name>
Functionshell-defined command bodyarguments, branching, policy, cleanup, handoffwhence -w <name>, type <name>, functions <name>
Builtincommand implemented by the shellcd, alias, type, functionswhence -w <name>
Hashed commandcached executable path remembered by the shellfaster lookup after discoveryhash, rehash, whence -w <name>
Executablereal file found through PATHagents, scripts, CI, subprocessescommand -v <name>, whence -p <name>, test -x
Environment variableprocess data inherited by child processesmarkers, config paths, feature togglesprint -r -- "$VAR"

Fast classification:

zsh
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:

Example:

zsh
alias l='ls -lah'

Use a function when the helper needs:

Example workflow helper:

zsh
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:

Use an executable wrapper when:

Wrapper shape:

zsh
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
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:

zsh
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:

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

Avoid that pattern for zsh function DSL files.

Bad pattern:

zsh
[[ -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:

zsh
funclist
funclist ai
funclist git
funclist -v x

Use funcwhere to locate the source:

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

Use funced when you are ready to inspect or edit:

zsh
funced xfl
funced xfc
funced fix

Plain rule:

snippet-19
funclist finds names.
funcwhere finds the file.
funced opens the definition.

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

zsh
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:

zsh
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:

snippet-22
`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:

Confirm What A Name Really Is

Use these in order.

zsh
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:

FindingSmallest Safe Move
alias onlyexpand it into the real command or convert it to a function
function onlyuse zsh -lc 'source ...; fn "$@"'
function plus executabledecide which layer each caller should use and prove both
executable onlycall it directly and verify PATH order
missing in zsh -lc, present in zsh -icsource the narrow defining file or keep it interactive-only
needed by CI or scriptscreate an executable wrapper
depends on prompt/completion/UI statekeep it interactive-only

Helper Families

FamilyExamplesWhat They Represent
Codex launch/fork/exportx, e, xfl, xfc, xportCodex wrapper, exec, fork, compact, transcript export
Prompt Builder handoffp-f, p-c, p-cmexplicit zsh handoff around function-backed workflows
Fix workflowfixterse bug report -> richer repair workflow
Git/checkpoint helperscfix, ghost-save, aicmworkflow compression around repo state
Utility cleanuppksk, kskalias vs function decision surface
Orchestration bridgemuxai, agent_chaintransition into panes, phases, and multi-agent flows

Ask The Agent This

Classify a broken helper:

snippet-24
`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:

snippet-25
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:

snippet-26
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:

zsh
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:

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

Recovery:

zsh
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:

zsh
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
zsh -lc "source ~/.config/zsh/conf.d/40-ai.zsh; xfc $prompt"

Good:

zsh
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:

References And Resources