---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-environment-reference"
title: "Reliable non-interactive shell environments: practical reference"
---

# Reliable non-interactive shell environments: practical reference

## Agent Setup Prompt

```text
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:

```text
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:

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

```text
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:

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

What the workflow gives you now:

```text
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:

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

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

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

```text
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:

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

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

```text
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:

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

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

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

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

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

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

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

- Common login-shell bridge: `~/.config/zsh/.zprofile`
- Common agent bootstrap: `~/.config/zsh/codex-env.zsh`
- Common PATH assembly: `~/.config/zsh/conf.d/00-path.zsh`
- Common AI helper DSL: `~/.config/zsh/conf.d/40-ai.zsh`
- Common AI fix helpers: `~/.config/zsh/conf.d/47-ai-fix.zsh`
- Common local overrides: `~/.config/zsh/local.zsh`
- Common startup regression tests: `~/.config/zsh/tests/startup-regression.zsh`
- Codex config: `~/.codex/config.toml`
- Zsh startup files: https://zsh.sourceforge.io/Intro/intro_3.html
- Zsh options and invocation: https://zsh.sourceforge.io/Doc/Release/Invocation.html
- OpenAI Codex: https://openai.com/codex/

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

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