{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-functions-practice",
  "slug": "shell-functions-practice",
  "title": "Shell functions, aliases, and executable boundaries: practice drills",
  "summary": "Eight exercises classify commands, inspect helper definitions and sources, practice discoverability tools, choose aliases/functions/executables, preserve arguments across zsh handoffs, build a webhook replay wrapper, and map orchestration responsibilities.",
  "category": "Tools",
  "tags": [
    "zsh",
    "helpers",
    "cli",
    "practice"
  ],
  "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!/exercises/03-zsh-functions-aliases.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 1: Classify Command Names",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 2: Function Versus Executable",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 3: Find The Source",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 4: Use `funclist`, `funcwhere`, And `funced`",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 5: Alias Or Function?",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 6: Write A Safe Handoff",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 7: Design An Executable Fallback",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 8: Section 4 Bridge",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 811,
  "url": "/topics/codex-shell-functions-practice/",
  "markdownUrl": "/markdown/codex-shell-functions-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-functions-practice.json",
  "headings": [
    {
      "id": "exercise-1-classify-command-names",
      "text": "Exercise 1: Classify Command Names",
      "level": 2
    },
    {
      "id": "exercise-2-function-versus-executable",
      "text": "Exercise 2: Function Versus Executable",
      "level": 2
    },
    {
      "id": "exercise-3-find-the-source",
      "text": "Exercise 3: Find The Source",
      "level": 2
    },
    {
      "id": "exercise-4-use-funclist-funcwhere-and-funced",
      "text": "Exercise 4: Use `funclist`, `funcwhere`, And `funced`",
      "level": 2
    },
    {
      "id": "exercise-5-alias-or-function",
      "text": "Exercise 5: Alias Or Function?",
      "level": 2
    },
    {
      "id": "exercise-6-write-a-safe-handoff",
      "text": "Exercise 6: Write A Safe Handoff",
      "level": 2
    },
    {
      "id": "exercise-7-design-an-executable-fallback",
      "text": "Exercise 7: Design An Executable Fallback",
      "level": 2
    },
    {
      "id": "exercise-8-section-4-bridge",
      "text": "Exercise 8: Section 4 Bridge",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Shell functions, aliases, and executable boundaries: practice drills\n\nThese exercises practice command diagnosis and wrapper design.\n\nThe goal is not to memorize every helper. The goal is to prove what a command name is and choose the right integration pattern.\n\n## Exercise 1: Classify Command Names\n\nRun:\n\n```zsh\nfor name in alias cd git l rm x xi xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain; do\n  printf \"%-14s \" \"$name\"\n  whence -w \"$name\" 2>/dev/null || echo MISSING\ndone\n```\n\nFill out:\n\n```markdown\n# Command Classification\n\n| Name | alias / function / builtin / command / missing | Notes |\n| --- | --- | --- |\n| alias | | |\n| cd | | |\n| git | | |\n| xfl | | |\n| xfc | | |\n| xport | | |\n| fix | | |\n| muxai | | |\n| agent_chain | | |\n```\n\nQuestions:\n\n- Which names are portable executables?\n- Which names only exist inside zsh?\n- Which names are workflow wrappers?\n\n## Exercise 2: Function Versus Executable\n\nPick three helpers:\n\n```text\nxfl\nxfc\nxport\np-f\np-c\nfix\nagent_chain\nmuxai\nghost-save\npksk\n```\n\nRun:\n\n```zsh\nfor name in xfl xfc xport; do\n  echo \"== $name ==\"\n  whence -w \"$name\" 2>/dev/null || true\n  type \"$name\" 2>/dev/null || true\n  command -v \"$name\" 2>/dev/null || true\n  whence -p \"$name\" 2>/dev/null || true\ndone\n```\n\nFill out:\n\n```markdown\n# Function Versus Executable\n\n| Helper | `whence -w` result | `command -v` result | `whence -p` result | Needs executable fallback? |\n| --- | --- | --- | --- | --- |\n| | | | | |\n```\n\n## Exercise 3: Find The Source\n\nPick one helper:\n\n```text\nxfl\nxfc\nxport\np-f\np-c\nfix\nghost-save\npksk\nmuxai\nagent_chain\n```\n\nRun:\n\n```zsh\nwhence -w <name>\nfuncwhere <name>\nfunctions <name> | sed -n '1,120p'\n```\n\nFill out:\n\n```markdown\n# Function Reading Notes\n\n- helper:\n- kind:\n- source file:\n- purpose:\n- arguments:\n- external tools called:\n- files or git state it may change:\n- why this is a function instead of an alias:\n- one way to confirm it worked:\n- one failure mode:\n```\n\n## Exercise 4: Use `funclist`, `funcwhere`, And `funced`\n\nRun:\n\n```zsh\nfunclist\nfunclist ai\nfunclist git\nfunclist -v x\n```\n\nThen pick a helper and run:\n\n```zsh\nfuncwhere <name>\nfunced <name>\n```\n\nFill out:\n\n```markdown\n# Discoverability Notes\n\n- topic searched:\n- helper found:\n- source file:\n- what `funclist` showed:\n- what `funcwhere` showed:\n- whether `funced` opened the expected source:\n- one improvement you would make to the helper comment or description:\n```\n\n## Exercise 5: Alias Or Function?\n\nFor each proposed helper, decide alias, function, executable wrapper, or no helper.\n\n| Desired Helper | Your Choice | Why |\n| --- | --- | --- |\n| `l` runs `ls -lah` | | |\n| `rm` routes to trash only when installed | | |\n| `replay-webhook <fixture>` runs a command, captures logs, and prints pass/fail | | |\n| `xport` exports the latest Codex transcript and optionally saves markdown | | |\n| `pksk` terminates process groups and cleans matching app processes | | |\n| `agent_chain` runs gated explore-plan-implement phases | | |\n| `ci-smoke` must run from GitHub Actions | | |\n\n## Exercise 6: Write A Safe Handoff\n\nScenario: Prompt Builder or another tool needs to call `xfc`, but `xfc` is a zsh function.\n\nDiagnose:\n\n```zsh\nwhence -w xfc\nfuncwhere xfc\nwhence -p xfc || true\n```\n\nWrite a safe handoff:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' xfc \"continue the failing billing webhook investigation\"\n```\n\nAdapt the pattern for:\n\n```text\nxfl\nxport\np-f\np-c\n```\n\n## Exercise 7: Design An Executable Fallback\n\nScenario: the project has a repeated workflow for replaying billing webhooks. It must work from zsh, scripts, CI, and agents.\n\nCreate a wrapper shape:\n\n```zsh\nmkdir -p bin\ncat > bin/replay-webhook <<'EOF'\n#!/usr/bin/env zsh\nset -euo pipefail\nfixture=\"${1:?Usage: replay-webhook <fixture>}\"\npnpm test:billing-webhook -- \"$fixture\"\nEOF\nchmod +x bin/replay-webhook\n```\n\nConfirm it:\n\n```zsh\nzsh -lc 'PATH=\"$PWD/bin:$PATH\"; p=\"$(command -v replay-webhook)\"; print -r -- \"$p\"; test -x \"$p\"'\nzsh -lc 'PATH=\"$PWD/bin:$PATH\"; replay-webhook sample-fixture'\n```\n\nFill out:\n\n```markdown\n# Executable Fallback Design\n\n- wrapper path:\n- shebang:\n- required arguments:\n- underlying command:\n- confirmation command:\n- why executable instead of function:\n```\n\n## Exercise 8: Section 4 Bridge\n\nRun:\n\n```zsh\nwhence -w muxai agent_chain xfl xfc xport p-f p-c\nfuncwhere muxai\nfuncwhere agent_chain\n```\n\nFill out:\n\n```markdown\n# Section 4 Bridge Notes\n\n- helpers that create or manage workspace shape:\n- helpers that fork or compact Codex threads:\n- helpers that export context:\n- helpers that run multi-agent phases:\n- what needs a pane/thread/layout confirmation:\n- what another agent would need to resume:\n```\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/)"
}
