Reliable non-interactive shell environments: team walkthrough

Diagnosing agent tool visibility through non-interactive login-shell startup, agent-safe PATH configuration, executable precedence, clean-shell checks, and separation of interactive helpers from executable setup.

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

  1. Show the failure: bun: command not found.
  2. Explain zsh -lc: login, not interactive.
  3. Show the source-of-truth files.
  4. Run the basic confirmation command.
  5. Show PATH order.
  6. Explain .zshrc versus codex-env.zsh.
  7. Bridge to Section 3.

Expanded Walkthrough

Add:

  • clean-shell check
  • wrong executable wins
  • installer wrote .zshrc
  • local.zsh versus 00-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:

.zshrc is 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 -lc is the shell shape.
  • .zprofile and codex-env.zsh are the bridge.
  • .zshrc is not the default fix for agent command visibility.
  • command -v proves tool visibility.
  • env -u CODEX_AGENT_ENV_SOURCED validates 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.

Source references