Shell functions, aliases, and executable boundaries: team walkthrough

Shell command classification, alias/function/executable tradeoffs, helper discovery and source lookup, interactive inspection versus login-shell handoff, workflow helper families, and executable fallbacks for scripts and CI.

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:

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 -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-save
  • cfix
  • lazy stub internals
  • Prompt Builder details beyond p-f and p-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

Source references