{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-environment-reference",
  "slug": "shell-environment-reference",
  "title": "Reliable non-interactive shell environments: practical reference",
  "summary": "Step-by-step agent setup prompt and troubleshooting reference for non-interactive zsh startup, ZDOTDIR, deterministic PATH, safe environment bootstrapping, opt-in helper loading, Codex launch wrappers and configuration, executable fallbacks, targeted…",
  "category": "Tools",
  "tags": [
    "zsh",
    "environment",
    "path"
  ],
  "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!/cheatsheets/02-loading-zsh-env-into-codex.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/The Mental Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Visibility Layers",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Opt-In Function Loading",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/What The Marker Does",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/The Opt-In Marker Is Not Interactive Startup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/What To Confirm",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Confirm The Opt-In Marker",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Handoff To Section 3",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Inspect PATH Order",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Clean-Shell Check",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Where Fixes Usually Belong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Tool Works In Terminal, Missing In Codex",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Wrong Executable Wins",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Agent Startup Hangs",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Secrets Leak Risk",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Tool Visibility Works, But A Helper Name Is Missing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 2822,
  "url": "/topics/codex-shell-environment-reference/",
  "markdownUrl": "/markdown/codex-shell-environment-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-environment-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "the-mental-model",
      "text": "The Mental Model",
      "level": 2
    },
    {
      "id": "visibility-layers",
      "text": "Visibility Layers",
      "level": 2
    },
    {
      "id": "opt-in-function-loading",
      "text": "Opt-In Function Loading",
      "level": 2
    },
    {
      "id": "what-the-marker-does",
      "text": "What The Marker Does",
      "level": 2
    },
    {
      "id": "the-opt-in-marker-is-not-interactive-startup",
      "text": "The Opt-In Marker Is Not Interactive Startup",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm",
      "text": "What To Confirm",
      "level": 2
    },
    {
      "id": "confirm-the-opt-in-marker",
      "text": "Confirm The Opt-In Marker",
      "level": 2
    },
    {
      "id": "handoff-to-section-3",
      "text": "Handoff To Section 3",
      "level": 2
    },
    {
      "id": "inspect-path-order",
      "text": "Inspect PATH Order",
      "level": 2
    },
    {
      "id": "clean-shell-check",
      "text": "Clean-Shell Check",
      "level": 2
    },
    {
      "id": "where-fixes-usually-belong",
      "text": "Where Fixes Usually Belong",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "tool-works-in-terminal-missing-in-codex",
      "text": "Tool Works In Terminal, Missing In Codex",
      "level": 3
    },
    {
      "id": "wrong-executable-wins",
      "text": "Wrong Executable Wins",
      "level": 3
    },
    {
      "id": "agent-startup-hangs",
      "text": "Agent Startup Hangs",
      "level": 3
    },
    {
      "id": "secrets-leak-risk",
      "text": "Secrets Leak Risk",
      "level": 3
    },
    {
      "id": "tool-visibility-works-but-a-helper-name-is-missing",
      "text": "Tool Visibility Works, But A Helper Name Is Missing",
      "level": 3
    },
    {
      "id": "how-to-know-it-worked",
      "text": "How To Know It Worked",
      "level": 2
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Reliable non-interactive shell environments: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells.\n\nStep 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nDo not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables.\n\nStep 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as:\n\n    export ZDOTDIR=\"${ZDOTDIR:-$HOME/.config/zsh}\"\n\nVerify:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; test -d \"$ZDOTDIR\" && echo \"ZDOTDIR exists\" || echo \"ZDOTDIR missing\"'\n\nStep 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides.\n\nUse this shape, adjusted to the existing files:\n\n    [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n    [[ -r \"$ZDOTDIR/conf.d/00-path.zsh\" ]] && source \"$ZDOTDIR/conf.d/00-path.zsh\"\n    [[ -r \"$ZDOTDIR/local.zsh\" ]] && source \"$ZDOTDIR/local.zsh\"\n\nStep 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded:\n\n    export CODEX_AGENT_ENV_SOURCED=1\n\nDo not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here.\n\nStep 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins.\n\nVerify PATH order:\n\n    zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n\nVerify executable resolution:\n\n    zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n\nStep 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints.\n\nStep 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup.\n\nStep 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`.\n\nAdd this in the agent-safe startup path after `ZDOTDIR` is available:\n\n    if [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n      [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n    fi\n\nVerify the marker is absent by default:\n\n    zsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n\nVerify selected helper loading when requested:\n\n    CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nStep 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers:\n\n    xi() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n    }\n\n    x() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\n    e() {\n      codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\nOnly add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL:\n\n    [shell_environment_policy.set]\n    CODEX_LOAD_ZSH_DSL = \"1\"\n\nOtherwise, keep the marker out of global config and use the wrappers.\n\nVerify wrapper policy wiring:\n\n    zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true\n    rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n\nStep 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state.\n\n    zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\n    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'\n\nExpected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed.\n\nStep 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`.\n\nStep 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`.\n```\n\n## Big Idea\n\nWhen Codex runs a shell command, it is not inside your current terminal session.\n\nThis section answers one question:\n\n```text\nWhat can Codex see when it runs a non-interactive login shell through `zsh -lc`?\n```\n\nFocus here on startup files, PATH order, environment markers, and project tools. Leave command-name classification for Section 3.\n\n## Try This Now\n\nRun the same shell shape Codex commonly uses:\n`zsh -lc 'echo ZDOTDIR=$ZDOTDIR; command -v bun pnpm cargo codex packx || true'`\nIf a project tool is missing here, fix agent-safe startup before changing the prompt.\n\n## Files To Inspect\n\nCommon files that define shell behavior:\n\n```text\n~/.zshenv\n~/.config/zsh/.zprofile\n~/.config/zsh/codex-env.zsh\n~/.config/zsh/conf.d/00-path.zsh\n~/.config/zsh/conf.d/40-ai.zsh\n~/.config/zsh/local.zsh\n~/.config/zsh/tests/startup-regression.zsh\n~/.codex/config.toml\n```\n\nAdjust paths for the local machine. Keep non-interactive startup setup in the agent-safe path.\n\n## When To Reach For This\n\nUse this workflow when:\n\n- Codex says a project executable is `command not found`\n- a tool works in your terminal but fails inside Codex\n- a project depends on Bun, pnpm, Cargo, PackX, Homebrew tools, or custom CLIs\n- you installed a tool but the agent still cannot run it\n- a workflow depends on PATH order\n- the wrong executable version wins inside Codex\n- selected agent-safe zsh files should load only when the opt-in marker is present\n- you need to decide whether PATH setup belongs in `.zprofile`, `codex-env.zsh`, `00-path.zsh`, or `local.zsh`\n\nSkip this workflow when the question is:\n\n```text\nIs this command name an alias, function, builtin, hashed command, executable, or missing helper?\n```\n\nThat is Section 3.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nIf a command works in your terminal, Codex can run it the same way.\n```\n\nWhat the workflow gives you now:\n\n```text\nCodex runs through a non-interactive shell. Ask it to prove each required tool\nresolves from `zsh -lc` before relying on the command.\n```\n\n## The Mental Model\n\nCodex commonly runs commands through a shell shape like:\n\n```bash\nzsh -lc '<command>'\n```\n\nThat means:\n\n- `zsh`: run zsh\n- `-l`: login shell\n- `-c`: run a command string\n\nIt is login, but not interactive.\n\nThat distinction matters:\n\n| File Or Setting | Role |\n| --- | --- |\n| `~/.zshenv` | earliest bootstrap; points zsh toward XDG config |\n| `ZDOTDIR` | tells zsh where `.zprofile`, `.zshrc`, and related files live |\n| `$ZDOTDIR/.zprofile` | login-shell bridge for `zsh -lc` |\n| `$ZDOTDIR/codex-env.zsh` | agent-safe environment bootstrap |\n| `$ZDOTDIR/conf.d/00-path.zsh` | deterministic PATH assembly |\n| `$ZDOTDIR/conf.d/40-ai.zsh` | selected AI/Codex helper functions loaded only when opted in |\n| `$ZDOTDIR/local.zsh` | machine-specific safe overrides |\n| `$ZDOTDIR/.zshrc` | human interactive terminal startup |\n\nPractical rule:\n\n```text\nPut PATH and non-interactive-safe tool setup in the agent path.\nPut prompt, completion, keybindings, and terminal UI in `.zshrc`.\n```\n\n## Visibility Layers\n\nKeep three layers separate.\n\n| Layer | What It Means | Section 2 Question |\n| --- | --- | --- |\n| Environment variable | inherited process data | is the variable present in `zsh -lc`? |\n| PATH executable | real file found through PATH | does `command -v <name>` resolve in `zsh -lc`? |\n| Opt-in zsh helper file | selected source file loaded by marker | does the marker cause the safe file to load? |\n\nThis section proves the environment and PATH layer.\nSection 3 classifies individual command names.\n\n## Opt-In Function Loading\n\nA common setup uses a local marker:\n\n```text\nCODEX_LOAD_ZSH_DSL=1\n```\n\n`CODEX_LOAD_ZSH_DSL` is a local opt-in marker for this shell setup.\n\nCodex can inject that marker into shell-like tool processes with `shell_environment_policy.set`:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n```\n\nThat marker can be wrapped in opt-in launchers:\n\n```zsh\nx() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\ne() {\n  codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n```\n\nThe important part is the `-c` override:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\ncodex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n```\n\nPrefer wrapper-local `-c` flags when the behavior should be explicit and reversible. Use a global `~/.codex/config.toml` setting only when every Codex launch should load the DSL:\n\n```toml\n[shell_environment_policy.set]\nCODEX_LOAD_ZSH_DSL = \"1\"\n```\n\nUse the global setting only when you want that behavior all the time. Otherwise, keep `CODEX_LOAD_ZSH_DSL` out of `~/.codex/config.toml` and put it on the specific wrappers that need zsh helper functions.\n\n## What The Marker Does\n\nThe marker lets the zsh bootstrap source a small set of agent-safe files instead of the full interactive `.zshrc`.\n\nShape:\n\n```zsh\nif [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n  [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n  [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\nfi\n```\n\nLoad selected helpers only. Keep the full interactive terminal experience out of agent shells.\n\nDo not source all of `.zshrc` into agent shells. Interactive startup often includes prompts, completions, keybindings, fuzzy finders, terminal hooks, and profiling code that can slow, hang, spam, or mutate non-interactive agent commands.\n\n## The Opt-In Marker Is Not Interactive Startup\n\n`x` and `e` can make Codex set `CODEX_LOAD_ZSH_DSL=1`, but that does not mean the full interactive shell is loaded.\n\nThe marker should load only selected agent-safe files.\n\nExpected shape:\n\n```text\nCODEX_LOAD_ZSH_DSL=1\n-> zsh startup\n-> codex-env.zsh\n-> selected safe helper files\n-> no prompt, completion, keybindings, fuzzy finder, or terminal UI\n```\n\nQuick visibility check:\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n```\n\nIf a helper name is missing after this works, do not diagnose it as a broken PATH. Diagnose it in Section 3 as a command-name, source-file, or executable-fallback question.\n\n## Ask The Agent This\n\nFor a missing tool:\n\n```text\nCodex cannot find `bun`, but it works in my terminal.\n\nInspect the zsh startup path for non-interactive commands. Check `zsh -lc`,\n`ZDOTDIR`, `codex-env.zsh`, PATH order, and where Bun is installed. Do not\ndump secrets or full environment output. Tell me which file should change and\nhow to confirm it worked.\n```\n\nFor a new project tool:\n\n```text\nThis project needs `my-tool` available to Codex.\n\nInspect the existing agent-safe zsh setup and recommend where the PATH entry or\nwrapper should live. Keep interactive shell behavior out of the agent startup\npath. Include a short command that confirms `my-tool` resolves in `zsh -lc`.\n```\n\nFor PATH confusion:\n\n```text\nThe wrong version of `node` or `pnpm` is winning inside Codex.\n\nInspect PATH order from `zsh -lc`, compare executable locations with `whence -a`,\nand identify the smallest safe config change. Do not modify `.zshrc` unless the\nproblem is only interactive terminal behavior.\n```\n\nFor opt-in marker boundaries:\n\n```text\nI want Codex tool shells to load only selected agent-safe zsh files without\nsourcing the full interactive `.zshrc`.\n\nInspect `~/.codex/config.toml`, `shell_environment_policy.set`,\n`CODEX_LOAD_ZSH_DSL`, `~/.config/zsh/.zshenv`, `codex-env.zsh`, and\n`conf.d/40-ai.zsh`. Confirm the marker is explicit and reversible. If an\nindividual helper name is missing after the marker works, stop and classify that\nname with Section 3.\n```\n\n## What To Confirm\n\nThe basic confirmation shape:\n\n```bash\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\nWhat to look for:\n\n- `CODEX_AGENT_ENV_SOURCED=1`\n- `ZDOTDIR` points at the intended zsh config\n- required tools print real paths\n- missing tools are named plainly\n- no secrets are printed\n\nA known-good output shape looks like:\n\n```text\nCODEX_AGENT_ENV_SOURCED=1\nZDOTDIR=/path/to/home/.config/zsh\n/path/to/home/.cargo/bin/codex\n/path/to/home/.bun/bin/bun\n/usr/local/bin/pnpm\n/path/to/home/.cargo/bin/cargo\n/path/to/home/.bun/bin/packx\n```\n\nUse local paths. Keep the proof shape.\n\n## Confirm The Opt-In Marker\n\nProve the marker is absent by default:\n\n```bash\nzsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n```\n\nProve the agent-safe files load when the marker is present:\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n```\n\nInspect the Codex-side policy:\n\n```bash\nzsh -ic 'functions x; functions e' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'\nrg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n```\n\nWhat to look for:\n\n- `x` and `e` pass the marker through Codex with `-c`\n- global config does not set the marker unless you want it always on\n- tool visibility still works when the marker is present\n\n## Handoff To Section 3\n\nAfter `zsh -lc` proves the environment and PATH are correct, stop treating every missing name as a startup problem.\n\nNext question:\n\n```text\nWhat kind of command name is this?\n```\n\nUse Section 3 to classify aliases, functions, builtins, hashed commands, executables, missing helpers, and executable fallback decisions.\n\n## Inspect PATH Order\n\nPATH order decides which executable wins.\n\n```bash\nzsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n```\n\nLook for:\n\n- project tool paths before system fallbacks when appropriate\n- Bun, pnpm, Cargo, Homebrew, and local bin locations\n- duplicate or surprising entries\n- installer edits that only touched `.zshrc`\n\n## Clean-Shell Check\n\nThe marker `CODEX_AGENT_ENV_SOURCED=1` can be inherited by nested shells. When testing startup from scratch, unset it:\n\n```bash\nenv -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'\n```\n\nIf the bootstrap works, the command should still end up with `CODEX_AGENT_ENV_SOURCED=1`.\n\n## Where Fixes Usually Belong\n\n| Problem | Usually Belongs In |\n| --- | --- |\n| persistent PATH assembly | `~/.config/zsh/conf.d/00-path.zsh` |\n| machine-local safe override | `~/.config/zsh/local.zsh` |\n| agent-safe tool env | `~/.config/zsh/codex-env.zsh` |\n| selected agent-safe functions | `~/.config/zsh/conf.d/40-ai.zsh` behind `CODEX_LOAD_ZSH_DSL` |\n| login-shell bridge | `~/.config/zsh/.zprofile` |\n| prompt, completion, keybindings | `~/.config/zsh/.zshrc` |\n| reusable project command | executable wrapper on PATH |\n| rich alias/function workflow | function or executable-wrapper design |\n\n## If It Goes Wrong\n\n### Tool Works In Terminal, Missing In Codex\n\nLikely cause:\n\n- installer modified `.zshrc`\n- Codex runs `zsh -lc`\n- `.zshrc` is interactive startup, not the agent-safe bridge\n\nConfirm:\n\n```bash\nzsh -lc 'command -v bun || echo \"bun missing from zsh -lc\"'\n```\n\nThen inspect `codex-env.zsh`, `00-path.zsh`, and `local.zsh`.\n\n### Wrong Executable Wins\n\nUse:\n\n```bash\nzsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n```\n\nThe first matching executable is what the shell runs.\n\n### Agent Startup Hangs\n\nLikely cause:\n\n- prompt setup\n- completion setup\n- `fzf`\n- keybindings\n- terminal UI\n- interactive confirmation\n\nThose belong in `.zshrc` or behind an interactive guard, not in agent-safe startup.\n\n### Secrets Leak Risk\n\nDo not paste full `env` output into chat.\n\nUse targeted checks:\n\n```bash\nzsh -lc 'command -v op >/dev/null 2>&1 && echo \"op:visible\" || echo \"op:missing\"'\n```\n\nConfirm helpers exist without printing secret values.\n\n### Tool Visibility Works, But A Helper Name Is Missing\n\nIf required project tools resolve but a helper such as `xfl`, `p-f`, `fix`, or `funcwhere` is missing, the environment may already be fine.\n\nConfirm the project tools first:\n\n```bash\nzsh -lc 'command -v bun pnpm cargo codex packx || true'\n```\n\nThen move to Section 3 and classify the helper name. Do not fix helper-name problems by sourcing all of `.zshrc` into agent shells.\n\n## How To Know It Worked\n\nYou are done when:\n\n- `zsh -lc` resolves the required project tools\n- the clean-shell check also resolves them\n- PATH order is explainable\n- the opt-in marker behavior is explicit and reversible\n- the fix is in an agent-safe file\n- `.zshrc` is not carrying agent-only setup\n- no startup command prints secrets or waits for UI\n- Codex can run the project command that originally failed\n- unresolved helper names have been handed to Section 3 instead of treated as PATH failures\n\n## References And Resources\n\n- Common login-shell bridge: `~/.config/zsh/.zprofile`\n- Common agent bootstrap: `~/.config/zsh/codex-env.zsh`\n- Common PATH assembly: `~/.config/zsh/conf.d/00-path.zsh`\n- Common AI helper DSL: `~/.config/zsh/conf.d/40-ai.zsh`\n- Common AI fix helpers: `~/.config/zsh/conf.d/47-ai-fix.zsh`\n- Common local overrides: `~/.config/zsh/local.zsh`\n- Common startup regression tests: `~/.config/zsh/tests/startup-regression.zsh`\n- Codex config: `~/.codex/config.toml`\n- Zsh startup files: https://zsh.sourceforge.io/Intro/intro_3.html\n- Zsh options and invocation: https://zsh.sourceforge.io/Doc/Release/Invocation.html\n- OpenAI Codex: https://openai.com/codex/\n\n## Operational boundaries\n\n- `--dangerously-bypass-approvals-and-sandbox` is a high-trust launch choice, not required for environment-marker injection. The shown `env -u` check clears one guard, not the entire inherited environment.\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/)"
}
