Reliable non-interactive shell environments: practical reference

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…

Agent Setup 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`.

Big Idea

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

This section answers one question:

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:

~/.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:

  • Codex says a project executable is command not found
  • a tool works in your terminal but fails inside Codex
  • a project depends on Bun, pnpm, Cargo, PackX, Homebrew tools, or custom CLIs
  • you installed a tool but the agent still cannot run it
  • a workflow depends on PATH order
  • the wrong executable version wins inside Codex
  • selected agent-safe zsh files should load only when the opt-in marker is present
  • you need to decide whether PATH setup belongs in .zprofile, codex-env.zsh, 00-path.zsh, or local.zsh

Skip this workflow when the question is:

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:

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

What the workflow gives you now:

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:

zsh -lc '<command>'

That means:

  • zsh: run zsh
  • -l: login shell
  • -c: run a command string

It is login, but not interactive.

That distinction matters:

File Or Setting Role
~/.zshenv earliest bootstrap; points zsh toward XDG config
ZDOTDIR tells zsh where .zprofile, .zshrc, and related files live
$ZDOTDIR/.zprofile login-shell bridge for zsh -lc
$ZDOTDIR/codex-env.zsh agent-safe environment bootstrap
$ZDOTDIR/conf.d/00-path.zsh deterministic PATH assembly
$ZDOTDIR/conf.d/40-ai.zsh selected AI/Codex helper functions loaded only when opted in
$ZDOTDIR/local.zsh machine-specific safe overrides
$ZDOTDIR/.zshrc human interactive terminal startup

Practical rule:

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.

Layer What It Means Section 2 Question
Environment variable inherited process data is the variable present in zsh -lc?
PATH executable real file found through PATH does command -v <name> resolve in zsh -lc?
Opt-in zsh helper file selected source file loaded by marker does 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:

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:

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

That marker can be wrapped in opt-in launchers:

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

  • CODEX_AGENT_ENV_SOURCED=1
  • ZDOTDIR points at the intended zsh config
  • required tools print real paths
  • missing tools are named plainly
  • no secrets are printed

A known-good output shape looks like:

CODEX_AGENT_ENV_SOURCED=1
ZDOTDIR=/path/to/home/.config/zsh
/path/to/home/.cargo/bin/codex
/path/to/home/.bun/bin/bun
/usr/local/bin/pnpm
/path/to/home/.cargo/bin/cargo
/path/to/home/.bun/bin/packx

Use local paths. Keep the proof shape.

Confirm The Opt-In Marker

Prove the marker is absent by default:

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

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

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:

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:

  • x and e pass the marker through Codex with -c
  • global config does not set the marker unless you want it always on
  • tool visibility still works when the marker is present

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:

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.

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

Look for:

  • project tool paths before system fallbacks when appropriate
  • Bun, pnpm, Cargo, Homebrew, and local bin locations
  • duplicate or surprising entries
  • installer edits that only touched .zshrc

Clean-Shell Check

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

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

Problem Usually 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 command executable wrapper on PATH
rich alias/function workflow function or executable-wrapper design

If It Goes Wrong

Tool Works In Terminal, Missing In Codex

Likely cause:

  • installer modified .zshrc
  • Codex runs zsh -lc
  • .zshrc is interactive startup, not the agent-safe bridge

Confirm:

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:

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:

  • prompt setup
  • completion setup
  • fzf
  • keybindings
  • terminal UI
  • interactive confirmation

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:

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:

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:

  • zsh -lc resolves the required project tools
  • the clean-shell check also resolves them
  • PATH order is explainable
  • the opt-in marker behavior is explicit and reversible
  • the fix is in an agent-safe file
  • .zshrc is not carrying agent-only setup
  • no startup command prints secrets or waits for UI
  • Codex can run the project command that originally failed
  • unresolved helper names have been handed to Section 3 instead of treated as PATH failures

References And Resources

Operational boundaries

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

Source references