These exercises practice diagnosing agent shell visibility without turning the session into a full dotfiles audit.
Exercise 1: Write A Missing Tool Prompt
Write a prompt that asks an agent to diagnose one missing tool.
Template:
Codex cannot find `<tool>`, but it works in my terminal.
Inspect the non-interactive zsh startup path. Check `zsh -lc`, `ZDOTDIR`,
the agent-safe bootstrap, PATH order, and where the tool is installed. Do not
print secrets or full environment output. Tell me which file should change and
how to confirm it worked.
Exercise 2: Agent Env Snapshot
Run the confirmation shape for your machine:
zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'
Write:
# Agent Env Snapshot
- shell shape:
- ZDOTDIR:
- marker:
- tools found:
- tools missing:
- next action:
Exercise 3: Number PATH
zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,30p"'
Write:
# PATH Notes
- first project/toolchain path:
- package manager path:
- language runtime path:
- Homebrew path:
- suspicious entries:
- what should move:
Exercise 4: Clean-Shell Check
env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'
Answer:
# Clean-Shell Check
- Did the marker become set again?
- Did required tools resolve?
- What changed compared to the normal check?
- What does that imply?
Exercise 5: Place The Fix
For each case, choose the right home:
| Case | File Or Form |
|---|---|
| persistent PATH assembly for all shells | |
| machine-local private path | |
| prompt theme | |
| keybinding | |
| reusable command needed outside zsh | |
| rich helper function for interactive work | |
| safe agent bootstrap |
Options:
~/.config/zsh/conf.d/00-path.zsh
~/.config/zsh/local.zsh
~/.config/zsh/codex-env.zsh
~/.config/zsh/.zshrc
executable wrapper on PATH
Section 3 zsh DSL
Exercise 6: Function Or Executable
Run:
zsh -lc 'for name in bun packx funclist fix agent_chain xfl; do echo "--- $name ---"; command -v "$name" 2>/dev/null || echo "command -v: missing"; whence -w "$name" 2>/dev/null || echo "whence: missing"; done'
Classify:
# Function Versus Executable
| name | executable / function / missing | Section 2 or Section 3? | why |
| --- | --- | --- | --- |
| bun | | | |
| packx | | | |
| funclist | | | |
| fix | | | |
| agent_chain | | | |
| xfl | | | |