---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-functions-practice"
title: "Shell functions, aliases, and executable boundaries: practice drills"
---

# Shell functions, aliases, and executable boundaries: practice drills

These exercises practice command diagnosis and wrapper design.

The goal is not to memorize every helper. The goal is to prove what a command name is and choose the right integration pattern.

## Exercise 1: Classify Command Names

Run:

```zsh
for name in alias cd git l rm x xi xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain; do
  printf "%-14s " "$name"
  whence -w "$name" 2>/dev/null || echo MISSING
done
```

Fill out:

```markdown
# Command Classification

| Name | alias / function / builtin / command / missing | Notes |
| --- | --- | --- |
| alias | | |
| cd | | |
| git | | |
| xfl | | |
| xfc | | |
| xport | | |
| fix | | |
| muxai | | |
| agent_chain | | |
```

Questions:

- Which names are portable executables?
- Which names only exist inside zsh?
- Which names are workflow wrappers?

## Exercise 2: Function Versus Executable

Pick three helpers:

```text
xfl
xfc
xport
p-f
p-c
fix
agent_chain
muxai
ghost-save
pksk
```

Run:

```zsh
for name in xfl xfc xport; do
  echo "== $name =="
  whence -w "$name" 2>/dev/null || true
  type "$name" 2>/dev/null || true
  command -v "$name" 2>/dev/null || true
  whence -p "$name" 2>/dev/null || true
done
```

Fill out:

```markdown
# Function Versus Executable

| Helper | `whence -w` result | `command -v` result | `whence -p` result | Needs executable fallback? |
| --- | --- | --- | --- | --- |
| | | | | |
```

## Exercise 3: Find The Source

Pick one helper:

```text
xfl
xfc
xport
p-f
p-c
fix
ghost-save
pksk
muxai
agent_chain
```

Run:

```zsh
whence -w <name>
funcwhere <name>
functions <name> | sed -n '1,120p'
```

Fill out:

```markdown
# Function Reading Notes

- helper:
- kind:
- source file:
- purpose:
- arguments:
- external tools called:
- files or git state it may change:
- why this is a function instead of an alias:
- one way to confirm it worked:
- one failure mode:
```

## Exercise 4: Use `funclist`, `funcwhere`, And `funced`

Run:

```zsh
funclist
funclist ai
funclist git
funclist -v x
```

Then pick a helper and run:

```zsh
funcwhere <name>
funced <name>
```

Fill out:

```markdown
# Discoverability Notes

- topic searched:
- helper found:
- source file:
- what `funclist` showed:
- what `funcwhere` showed:
- whether `funced` opened the expected source:
- one improvement you would make to the helper comment or description:
```

## Exercise 5: Alias Or Function?

For each proposed helper, decide alias, function, executable wrapper, or no helper.

| Desired Helper | Your Choice | Why |
| --- | --- | --- |
| `l` runs `ls -lah` | | |
| `rm` routes to trash only when installed | | |
| `replay-webhook <fixture>` runs a command, captures logs, and prints pass/fail | | |
| `xport` exports the latest Codex transcript and optionally saves markdown | | |
| `pksk` terminates process groups and cleans matching app processes | | |
| `agent_chain` runs gated explore-plan-implement phases | | |
| `ci-smoke` must run from GitHub Actions | | |

## Exercise 6: Write A Safe Handoff

Scenario: Prompt Builder or another tool needs to call `xfc`, but `xfc` is a zsh function.

Diagnose:

```zsh
whence -w xfc
funcwhere xfc
whence -p xfc || true
```

Write a safe handoff:

```zsh
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' xfc "continue the failing billing webhook investigation"
```

Adapt the pattern for:

```text
xfl
xport
p-f
p-c
```

## Exercise 7: Design An Executable Fallback

Scenario: the project has a repeated workflow for replaying billing webhooks. It must work from zsh, scripts, CI, and agents.

Create a wrapper shape:

```zsh
mkdir -p bin
cat > bin/replay-webhook <<'EOF'
#!/usr/bin/env zsh
set -euo pipefail
fixture="${1:?Usage: replay-webhook <fixture>}"
pnpm test:billing-webhook -- "$fixture"
EOF
chmod +x bin/replay-webhook
```

Confirm it:

```zsh
zsh -lc 'PATH="$PWD/bin:$PATH"; p="$(command -v replay-webhook)"; print -r -- "$p"; test -x "$p"'
zsh -lc 'PATH="$PWD/bin:$PATH"; replay-webhook sample-fixture'
```

Fill out:

```markdown
# Executable Fallback Design

- wrapper path:
- shebang:
- required arguments:
- underlying command:
- confirmation command:
- why executable instead of function:
```

## Exercise 8: Section 4 Bridge

Run:

```zsh
whence -w muxai agent_chain xfl xfc xport p-f p-c
funcwhere muxai
funcwhere agent_chain
```

Fill out:

```markdown
# Section 4 Bridge Notes

- helpers that create or manage workspace shape:
- helpers that fork or compact Codex threads:
- helpers that export context:
- helpers that run multi-agent phases:
- what needs a pane/thread/layout confirmation:
- what another agent would need to resume:
```

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