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
- Start from Section 2 executable proof.
- Classify helpers with
whence -w. - Show alias versus function.
- Show function versus executable.
- Locate a helper with
funcwhere. - Show a safe
zsh -lchandoff. - Bridge to Section 4.
Expanded Walkthrough
Add:
funclist,funcwhere,funcedxfl,xfc,xportp-f,p-c- lazy stub explanation
- executable fallback discussion
Deep-Dive Walkthrough
Add:
fixghost-savepksk- 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:
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 -icfor interactive discoveryzsh -lcfor non-interactive handofffunclist,funcwhere,funcedxfl,xfc,xportp-f,p-c- executable fallback
Live Demo
Start from Section 2 proof:
zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; command -v codex bun pnpm cargo packx || true'
Show helper visibility:
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:
funcwhere xfl
funcwhere xfc
funcwhere fix
funcwhere agent_chain
funcwhere muxai
Show safe handoff:
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:
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-savecfix- lazy stub internals
- Prompt Builder details beyond
p-fandp-c
If 20 minutes behind, run only:
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