{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-environment-team-guide",
  "slug": "shell-environment-team-guide",
  "title": "Reliable non-interactive shell environments: team walkthrough",
  "summary": "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.",
  "category": "Team practice",
  "tags": [
    "zsh",
    "environment",
    "path",
    "team-guide"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Do Not Over-Explain",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Preserve If Short On Time",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Boundary With Section 3",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 430,
  "url": "/topics/codex-shell-environment-team-guide/",
  "markdownUrl": "/markdown/codex-shell-environment-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-environment-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "do-not-over-explain",
      "text": "Do Not Over-Explain",
      "level": 2
    },
    {
      "id": "essential-points-to-preserve",
      "text": "Essential Points To Preserve",
      "level": 2
    },
    {
      "id": "boundary-with-section-3",
      "text": "Boundary With Section 3",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Reliable non-interactive shell environments: team walkthrough\n\n## Team Learning Goal\n\nTeach this as a tool-visibility workflow, not a dotfiles tour.\n\nThe 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.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Show the failure: `bun: command not found`.\n2. Explain `zsh -lc`: login, not interactive.\n3. Show the source-of-truth files.\n4. Run the basic confirmation command.\n5. Show PATH order.\n6. Explain `.zshrc` versus `codex-env.zsh`.\n7. Bridge to Section 3.\n\n### Expanded Walkthrough\n\nAdd:\n\n- clean-shell check\n- wrong executable wins\n- installer wrote `.zshrc`\n- `local.zsh` versus `00-path.zsh`\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- function versus executable\n- startup hangs from interactive code\n- secret-safe checks\n- team member exercise kickoff\n\n## Talking Points\n\nOpening:\n\n> Codex does not inherit your current terminal session. It gets a shell command environment. Prove what that environment can see.\n\nWhen showing `zsh -lc`:\n\n> Login, but not interactive.\n\nWhen showing `.zprofile`:\n\n> This is the bridge into the agent-safe environment.\n\nWhen showing `.zshrc`:\n\n> `.zshrc` is for humans. It is usually the wrong place to fix agent PATH.\n\nWhen showing `codex-env.zsh`:\n\n> This file should be boring. It gives agents tools, not terminal personality.\n\nWhen showing PATH:\n\n> PATH order decides reality. The first match wins.\n\n## Do Not Over-Explain\n\n- every zsh startup file in the manual\n- Oh My Zsh internals\n- every alias or function in John's setup\n- secret-management internals\n- prompt theme details\n- completion or ZLE mechanics\n\n## Essential Points To Preserve\n\n- `zsh -lc` is the shell shape.\n- `.zprofile` and `codex-env.zsh` are the bridge.\n- `.zshrc` is not the default fix for agent command visibility.\n- `command -v` proves tool visibility.\n- `env -u CODEX_AGENT_ENV_SOURCED` validates startup from scratch.\n\n## Boundary With Section 3\n\nSection 2 is about agent-safe executable environment.\n\nSection 3 is about zsh functions and aliases as workflow language.\n\n| Section 2 | Section 3 |\n| --- | --- |\n| `zsh -lc` proof | command DSL tour |\n| `.zprofile` | `.zshrc` |\n| `codex-env.zsh` | rich helper files |\n| deterministic PATH | aliases and functions |\n| `command -v` | `funclist`, `funcwhere`, `funced` |\n| missing-command debugging | workflow wrappers |\n| non-interactive safety | interactive productivity |\n\nBridge line:\n\n> Now that Codex can see the executables, Section 3 shows how John's zsh helpers become a workflow language.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
