Section 02

Loading ZSH Env Into Codex

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


setup agent prompt
Set 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.

Step 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only:

    zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; command -v bun pnpm cargo codex packx || true'

Do not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables.

Step 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as:

    export ZDOTDIR="${ZDOTDIR:-$HOME/.config/zsh}"

Verify:

    zsh -lc 'echo "ZDOTDIR=$ZDOTDIR"; test -d "$ZDOTDIR" && echo "ZDOTDIR exists" || echo "ZDOTDIR missing"'

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

Use this shape, adjusted to the existing files:

    [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh"
    [[ -r "$ZDOTDIR/conf.d/00-path.zsh" ]] && source "$ZDOTDIR/conf.d/00-path.zsh"
    [[ -r "$ZDOTDIR/local.zsh" ]] && source "$ZDOTDIR/local.zsh"

Step 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:

    export CODEX_AGENT_ENV_SOURCED=1

Do not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here.

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

Verify PATH order:

    zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"'

Verify executable resolution:

    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'

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

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

Step 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`.

Add this in the agent-safe startup path after `ZDOTDIR` is available:

    if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then
      [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh"
    fi

Verify the marker is absent by default:

    zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"'

Verify selected helper loading when requested:

    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'

Step 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:

    xi() {
      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@"
    }

    x() {
      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"
    }

    e() {
      codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"
    }

Only add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL:

    [shell_environment_policy.set]
    CODEX_LOAD_ZSH_DSL = "1"

Otherwise, keep the marker out of global config and use the wrappers.

Verify wrapper policy wiring:

    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
    rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true

Step 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state.

    zsh -lc 'echo "CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}"; echo "ZDOTDIR=$ZDOTDIR"; command -v codex bun pnpm cargo packx || true'

    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'

Expected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed.

Step 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>'`.

Step 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`.

Workflow route

Loading ZSH Env Into Codex

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

Eggo plugs the visible tool path into the correct shell lane for the Loading ZSH Env Into Codex workflow, making the page's operating move visible.
Intent

Name the software-workflow decision before launching work.

Evidence

Inspect the file, command, log, prompt, or recording that proves the state.

Route

Pick the narrow agent, tool, shell, or council path that matches the problem.

Verify

Confirm the result with output, screenshots, receipts, or saved decisions.

  1. Big Idea
  2. Try This Now
  3. Files To Inspect
  4. When To Reach For This
  5. How This Used To Work
  6. The Mental Model
the winning tool lights up while hidden shell-only helpers stay separate

Big Idea

When Codex runs a shell command, it is not inside your current terminal session.

This section answers one question:

snippet-1
What can Codex see when it runs a non-interactive login shell through `zsh -lc`?

Focus here on startup files, PATH order, environment markers, and project tools. Leave command-name classification for Section 3.

Try This Now

Run the same shell shape Codex commonly uses: zsh -lc 'echo ZDOTDIR=$ZDOTDIR; command -v bun pnpm cargo codex packx || true' If a project tool is missing here, fix agent-safe startup before changing the prompt.

Files To Inspect

Common files that define shell behavior:

snippet-2
~/.zshenv
~/.config/zsh/.zprofile
~/.config/zsh/codex-env.zsh
~/.config/zsh/conf.d/00-path.zsh
~/.config/zsh/conf.d/40-ai.zsh
~/.config/zsh/local.zsh
~/.config/zsh/tests/startup-regression.zsh
~/.codex/config.toml

Adjust paths for the local machine. Keep non-interactive startup setup in the agent-safe path.

When To Reach For This

Use this workflow when:

Skip this workflow when the question is:

snippet-3
Is this command name an alias, function, builtin, hashed command, executable, or missing helper?

That is Section 3.

How This Used To Work

What you used to expect:

snippet-4
If a command works in your terminal, Codex can run it the same way.

What the workflow gives you now:

snippet-5
Codex runs through a non-interactive shell. Ask it to prove each required tool
resolves from `zsh -lc` before relying on the command.

The Mental Model

Codex commonly runs commands through a shell shape like:

bash
zsh -lc '<command>'

That means:

It is login, but not interactive.

That distinction matters:

File Or SettingRole
~/.zshenvearliest bootstrap; points zsh toward XDG config
ZDOTDIRtells zsh where .zprofile, .zshrc, and related files live
$ZDOTDIR/.zprofilelogin-shell bridge for zsh -lc
$ZDOTDIR/codex-env.zshagent-safe environment bootstrap
$ZDOTDIR/conf.d/00-path.zshdeterministic PATH assembly
$ZDOTDIR/conf.d/40-ai.zshselected AI/Codex helper functions loaded only when opted in
$ZDOTDIR/local.zshmachine-specific safe overrides
$ZDOTDIR/.zshrchuman interactive terminal startup

Practical rule:

snippet-7
Put PATH and non-interactive-safe tool setup in the agent path.
Put prompt, completion, keybindings, and terminal UI in `.zshrc`.

Visibility Layers

Keep three layers separate.

LayerWhat It MeansSection 2 Question
Environment variableinherited process datais the variable present in zsh -lc?
PATH executablereal file found through PATHdoes command -v <name> resolve in zsh -lc?
Opt-in zsh helper fileselected source file loaded by markerdoes the marker cause the safe file to load?

This section proves the environment and PATH layer. Section 3 classifies individual command names.

Opt-In Function Loading

A common setup uses a local marker:

snippet-8
CODEX_LOAD_ZSH_DSL=1

CODEX_LOAD_ZSH_DSL is a local opt-in marker for this shell setup.

Codex can inject that marker into shell-like tool processes with shell_environment_policy.set:

bash
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"'

That marker can be wrapped in opt-in launchers:

zsh
x() {
  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"
}

e() {
  codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"
}

The important part is the -c override:

bash
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"
codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' --dangerously-bypass-approvals-and-sandbox "$@"

Prefer 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:

toml
[shell_environment_policy.set]
CODEX_LOAD_ZSH_DSL = "1"

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

What The Marker Does

The marker lets the zsh bootstrap source a small set of agent-safe files instead of the full interactive .zshrc.

Shape:

zsh
if [[ -n "${CODEX_LOAD_ZSH_DSL:-}" ]]; then
  [[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh"
  [[ -r "$ZDOTDIR/conf.d/40-ai.zsh" ]] && source "$ZDOTDIR/conf.d/40-ai.zsh"
fi

Load selected helpers only. Keep the full interactive terminal experience out of agent shells.

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

The Opt-In Marker Is Not Interactive Startup

x and e can make Codex set CODEX_LOAD_ZSH_DSL=1, but that does not mean the full interactive shell is loaded.

The marker should load only selected agent-safe files.

Expected shape:

snippet-14
CODEX_LOAD_ZSH_DSL=1
-> zsh startup
-> codex-env.zsh
-> selected safe helper files
-> no prompt, completion, keybindings, fuzzy finder, or terminal UI

Quick visibility check:

bash
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'

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

Ask The Agent This

For a missing tool:

snippet-16
Codex cannot find `bun`, but it works in my terminal.

Inspect the zsh startup path for non-interactive commands. Check `zsh -lc`,
`ZDOTDIR`, `codex-env.zsh`, PATH order, and where Bun is installed. Do not
dump secrets or full environment output. Tell me which file should change and
how to confirm it worked.

For a new project tool:

snippet-17
This project needs `my-tool` available to Codex.

Inspect the existing agent-safe zsh setup and recommend where the PATH entry or
wrapper should live. Keep interactive shell behavior out of the agent startup
path. Include a short command that confirms `my-tool` resolves in `zsh -lc`.

For PATH confusion:

snippet-18
The wrong version of `node` or `pnpm` is winning inside Codex.

Inspect PATH order from `zsh -lc`, compare executable locations with `whence -a`,
and identify the smallest safe config change. Do not modify `.zshrc` unless the
problem is only interactive terminal behavior.

For opt-in marker boundaries:

snippet-19
I want Codex tool shells to load only selected agent-safe zsh files without
sourcing the full interactive `.zshrc`.

Inspect `~/.codex/config.toml`, `shell_environment_policy.set`,
`CODEX_LOAD_ZSH_DSL`, `~/.config/zsh/.zshenv`, `codex-env.zsh`, and
`conf.d/40-ai.zsh`. Confirm the marker is explicit and reversible. If an
individual helper name is missing after the marker works, stop and classify that
name with Section 3.

What To Confirm

The basic confirmation shape:

bash
zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'

What to look for:

A known-good output shape looks like:

snippet-21
CODEX_AGENT_ENV_SOURCED=1
ZDOTDIR=/Users/you/.config/zsh
/Users/you/.cargo/bin/codex
/Users/you/.bun/bin/bun
/usr/local/bin/pnpm
/Users/you/.cargo/bin/cargo
/Users/you/.bun/bin/packx

Use local paths. Keep the proof shape.

Confirm The Opt-In Marker

Prove the marker is absent by default:

bash
zsh -lc 'echo "CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}"'

Prove the agent-safe files load when the marker is present:

bash
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'

Inspect the Codex-side policy:

bash
zsh -ic 'functions x; functions e' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'
rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true

What to look for:

Handoff To Section 3

After zsh -lc proves the environment and PATH are correct, stop treating every missing name as a startup problem.

Next question:

snippet-25
What kind of command name is this?

Use Section 3 to classify aliases, functions, builtins, hashed commands, executables, missing helpers, and executable fallback decisions.

Inspect PATH Order

PATH order decides which executable wins.

bash
zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n "1,25p"'

Look for:

Clean-Shell Check

The marker CODEX_AGENT_ENV_SOURCED=1 can be inherited by nested shells. When testing startup from scratch, unset it:

bash
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'

If the bootstrap works, the command should still end up with CODEX_AGENT_ENV_SOURCED=1.

Where Fixes Usually Belong

ProblemUsually Belongs In
persistent PATH assembly~/.config/zsh/conf.d/00-path.zsh
machine-local safe override~/.config/zsh/local.zsh
agent-safe tool env~/.config/zsh/codex-env.zsh
selected agent-safe functions~/.config/zsh/conf.d/40-ai.zsh behind CODEX_LOAD_ZSH_DSL
login-shell bridge~/.config/zsh/.zprofile
prompt, completion, keybindings~/.config/zsh/.zshrc
reusable project commandexecutable wrapper on PATH
rich alias/function workflowfunction or executable-wrapper design

If It Goes Wrong

Tool Works In Terminal, Missing In Codex

Likely cause:

Confirm:

bash
zsh -lc 'command -v bun || echo "bun missing from zsh -lc"'

Then inspect codex-env.zsh, 00-path.zsh, and local.zsh.

Wrong Executable Wins

Use:

bash
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'

The first matching executable is what the shell runs.

Agent Startup Hangs

Likely cause:

Those belong in .zshrc or behind an interactive guard, not in agent-safe startup.

Secrets Leak Risk

Do not paste full env output into chat.

Use targeted checks:

bash
zsh -lc 'command -v op >/dev/null 2>&1 && echo "op:visible" || echo "op:missing"'

Confirm helpers exist without printing secret values.

Tool Visibility Works, But A Helper Name Is Missing

If required project tools resolve but a helper such as xfl, p-f, fix, or funcwhere is missing, the environment may already be fine.

Confirm the project tools first:

bash
zsh -lc 'command -v bun pnpm cargo codex packx || true'

Then move to Section 3 and classify the helper name. Do not fix helper-name problems by sourcing all of .zshrc into agent shells.

How To Know It Worked

You are done when:

References And Resources