---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-functions-team-guide"
title: "Shell functions, aliases, and executable boundaries: team walkthrough"
---

# Shell functions, aliases, and executable boundaries: team walkthrough

## Team Learning Goal

Teach command diagnosis and workflow design, not a dotfiles tour.

The audience should leave knowing how to classify a command name, find its source, and decide whether it should be an alias, function, or executable wrapper.

## Walkthrough Depth

### Essential Walkthrough

1. Start from Section 2 executable proof.
2. Classify helpers with `whence -w`.
3. Show alias versus function.
4. Show function versus executable.
5. Locate a helper with `funcwhere`.
6. Show a safe `zsh -lc` handoff.
7. Bridge to Section 4.

### Expanded Walkthrough

Add:

- `funclist`, `funcwhere`, `funced`
- `xfl`, `xfc`, `xport`
- `p-f`, `p-c`
- lazy stub explanation
- executable fallback discussion

### Deep-Dive Walkthrough

Add:

- `fix`
- `ghost-save`
- `pksk`
- stdout/stderr contract
- team member DSL card exercise

## Talking Points

Opening:

> Aliases save keystrokes. Functions encode workflows.

On classification:

> The first move is not editing config. The first move is asking the shell what this name is.

On function versus executable:

> A zsh function is not a binary. A subprocess that looks for a file on PATH cannot run your function unless you deliberately load zsh around it.

On aliases:

> Aliases are substitutions. Useful, but not a programming language.

On functions:

> Functions are where arguments, policy, fallback, cleanup, and confirmation belong.

On executable fallbacks:

> If scripts, CI, or non-zsh callers need it, make it a real executable.

## Essential Points To Preserve

Preserve these commands:

```zsh
whence -w <name>
type <name>
alias <name>
functions <name>
command -v <name>
whence -p <name>
funcwhere <name>
```

Preserve these concepts:

- alias vs function
- function vs executable
- `zsh -ic` for interactive discovery
- `zsh -lc` for non-interactive handoff
- `funclist`, `funcwhere`, `funced`
- `xfl`, `xfc`, `xport`
- `p-f`, `p-c`
- executable fallback

## Live Demo

Start from Section 2 proof:

```zsh
zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; command -v codex bun pnpm cargo packx || true'
```

Show helper visibility:

```zsh
zsh -ic 'for name in funclist funcwhere funced x xi 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'
```

Show source:

```zsh
funcwhere xfl
funcwhere xfc
funcwhere fix
funcwhere agent_chain
funcwhere muxai
```

Show safe handoff:

```zsh
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'
```

Bridge to Section 4:

```zsh
whence -w muxai agent_chain
funcwhere muxai
funcwhere agent_chain
```

## Optional Depth

If 5 minutes behind, cut:

- function body reading
- helper family details
- stdout/stderr contract

If 10 minutes behind, cut:

- `ghost-save`
- `cfix`
- lazy stub internals
- Prompt Builder details beyond `p-f` and `p-c`

If 20 minutes behind, run only:

```zsh
zsh -ic 'for name in funclist funcwhere funced xfl xfc xport fix agent_chain muxai; do printf "%-14s " "$name"; whence -w "$name" 2>/dev/null || echo MISSING; done'
zsh -ic 'funcwhere xfl; funcwhere xfc; funcwhere fix; funcwhere agent_chain; funcwhere muxai'
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'
```

## Boundary With Section 4

Section 3 gives the command language. Section 4 puts that language into panes, threads, forks, transcript exports, and agent chains.

Bridge line:

> Section 3 made the commands real. Section 4 makes the commands addressable.

## Further References

- team member cheatsheet: `cheatsheets/03-zsh-functions-aliases.md`
- Exercises: `exercises/03-zsh-functions-aliases.md`
- Helper file: `zsh/conf.d/40-ai.zsh`
- Fix helper source: `zsh/conf.d/47-ai-fix.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

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