Team Learning Goal
Teach this as a tool-visibility workflow, not a dotfiles tour.
The audience should leave knowing how to ask an agent to inspect non-interactive shell startup, where safe PATH fixes belong, and how to confirm Codex can run the project tools.
Walkthrough Depth
Essential Walkthrough
- Show the failure:
bun: command not found. - Explain
zsh -lc: login, not interactive. - Show the source-of-truth files.
- Run the basic confirmation command.
- Show PATH order.
- Explain
.zshrcversuscodex-env.zsh. - Bridge to Section 3.
Expanded Walkthrough
Add:
- clean-shell check
- wrong executable wins
- installer wrote
.zshrc local.zshversus00-path.zsh
Deep-Dive Walkthrough
Add:
- function versus executable
- startup hangs from interactive code
- secret-safe checks
- team member exercise kickoff
Talking Points
Opening:
Codex does not inherit your current terminal session. It gets a shell command environment. Prove what that environment can see.
When showing zsh -lc:
Login, but not interactive.
When showing .zprofile:
This is the bridge into the agent-safe environment.
When showing .zshrc:
.zshrcis for humans. It is usually the wrong place to fix agent PATH.
When showing codex-env.zsh:
This file should be boring. It gives agents tools, not terminal personality.
When showing PATH:
PATH order decides reality. The first match wins.
Do Not Over-Explain
- every zsh startup file in the manual
- Oh My Zsh internals
- every alias or function in John's setup
- secret-management internals
- prompt theme details
- completion or ZLE mechanics
Essential Points To Preserve
zsh -lcis the shell shape..zprofileandcodex-env.zshare the bridge..zshrcis not the default fix for agent command visibility.command -vproves tool visibility.env -u CODEX_AGENT_ENV_SOURCEDvalidates startup from scratch.
Boundary With Section 3
Section 2 is about agent-safe executable environment.
Section 3 is about zsh functions and aliases as workflow language.
| Section 2 | Section 3 |
|---|---|
zsh -lc proof |
command DSL tour |
.zprofile |
.zshrc |
codex-env.zsh |
rich helper files |
| deterministic PATH | aliases and functions |
command -v |
funclist, funcwhere, funced |
| missing-command debugging | workflow wrappers |
| non-interactive safety | interactive productivity |
Bridge line:
Now that Codex can see the executables, Section 3 shows how John's zsh helpers become a workflow language.