{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-functions-team-guide",
  "slug": "shell-functions-team-guide",
  "title": "Shell functions, aliases, and executable boundaries: team walkthrough",
  "summary": "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.",
  "category": "Team practice",
  "tags": [
    "zsh",
    "helpers",
    "cli",
    "team-guide"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Preserve If Short On Time",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Live Demo",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Cut List",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Boundary With Section 4",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Presenter References",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 599,
  "url": "/topics/codex-shell-functions-team-guide/",
  "markdownUrl": "/markdown/codex-shell-functions-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-functions-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "essential-points-to-preserve",
      "text": "Essential Points To Preserve",
      "level": 2
    },
    {
      "id": "live-demo",
      "text": "Live Demo",
      "level": 2
    },
    {
      "id": "optional-depth",
      "text": "Optional Depth",
      "level": 2
    },
    {
      "id": "boundary-with-section-4",
      "text": "Boundary With Section 4",
      "level": 2
    },
    {
      "id": "further-references",
      "text": "Further References",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Shell functions, aliases, and executable boundaries: team walkthrough\n\n## Team Learning Goal\n\nTeach command diagnosis and workflow design, not a dotfiles tour.\n\nThe 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.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Start from Section 2 executable proof.\n2. Classify helpers with `whence -w`.\n3. Show alias versus function.\n4. Show function versus executable.\n5. Locate a helper with `funcwhere`.\n6. Show a safe `zsh -lc` handoff.\n7. Bridge to Section 4.\n\n### Expanded Walkthrough\n\nAdd:\n\n- `funclist`, `funcwhere`, `funced`\n- `xfl`, `xfc`, `xport`\n- `p-f`, `p-c`\n- lazy stub explanation\n- executable fallback discussion\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- `fix`\n- `ghost-save`\n- `pksk`\n- stdout/stderr contract\n- team member DSL card exercise\n\n## Talking Points\n\nOpening:\n\n> Aliases save keystrokes. Functions encode workflows.\n\nOn classification:\n\n> The first move is not editing config. The first move is asking the shell what this name is.\n\nOn function versus executable:\n\n> 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.\n\nOn aliases:\n\n> Aliases are substitutions. Useful, but not a programming language.\n\nOn functions:\n\n> Functions are where arguments, policy, fallback, cleanup, and confirmation belong.\n\nOn executable fallbacks:\n\n> If scripts, CI, or non-zsh callers need it, make it a real executable.\n\n## Essential Points To Preserve\n\nPreserve these commands:\n\n```zsh\nwhence -w <name>\ntype <name>\nalias <name>\nfunctions <name>\ncommand -v <name>\nwhence -p <name>\nfuncwhere <name>\n```\n\nPreserve these concepts:\n\n- alias vs function\n- function vs executable\n- `zsh -ic` for interactive discovery\n- `zsh -lc` for non-interactive handoff\n- `funclist`, `funcwhere`, `funced`\n- `xfl`, `xfc`, `xport`\n- `p-f`, `p-c`\n- executable fallback\n\n## Live Demo\n\nStart from Section 2 proof:\n\n```zsh\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; command -v codex bun pnpm cargo packx || true'\n```\n\nShow helper visibility:\n\n```zsh\nzsh -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'\n```\n\nShow source:\n\n```zsh\nfuncwhere xfl\nfuncwhere xfc\nfuncwhere fix\nfuncwhere agent_chain\nfuncwhere muxai\n```\n\nShow safe handoff:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'\n```\n\nBridge to Section 4:\n\n```zsh\nwhence -w muxai agent_chain\nfuncwhere muxai\nfuncwhere agent_chain\n```\n\n## Optional Depth\n\nIf 5 minutes behind, cut:\n\n- function body reading\n- helper family details\n- stdout/stderr contract\n\nIf 10 minutes behind, cut:\n\n- `ghost-save`\n- `cfix`\n- lazy stub internals\n- Prompt Builder details beyond `p-f` and `p-c`\n\nIf 20 minutes behind, run only:\n\n```zsh\nzsh -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'\nzsh -ic 'funcwhere xfl; funcwhere xfc; funcwhere fix; funcwhere agent_chain; funcwhere muxai'\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'\n```\n\n## Boundary With Section 4\n\nSection 3 gives the command language. Section 4 puts that language into panes, threads, forks, transcript exports, and agent chains.\n\nBridge line:\n\n> Section 3 made the commands real. Section 4 makes the commands addressable.\n\n## Further References\n\n- team member cheatsheet: `cheatsheets/03-zsh-functions-aliases.md`\n- Exercises: `exercises/03-zsh-functions-aliases.md`\n- Helper file: `zsh/conf.d/40-ai.zsh`\n- Fix helper source: `zsh/conf.d/47-ai-fix.zsh`\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n- Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
