---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-environment-team-guide"
title: "Reliable non-interactive shell environments: team walkthrough"
---

# Reliable non-interactive shell environments: team walkthrough

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

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