---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-functions-reference"
title: "Shell functions, aliases, and executable boundaries: practical reference"
---

# Shell functions, aliases, and executable boundaries: practical reference

## Agent Setup Prompt

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

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

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

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

What the workflow gives you now:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- 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

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

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

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
