---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-startup-files"
title: "Agent-safe shell startup file examples"
---

# Agent-safe shell startup file examples

These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.

## Safety and completeness boundaries

- These are setup examples, not a drop-in configuration. The home-directory `.zshenv` forwards to `$ZDOTDIR/.zshenv`; do not install the same forwarding file at both locations.
- The supplied bootstrap does not implement the `CODEX_LOAD_ZSH_DSL` opt-in loader described by the practical reference. Setting the marker alone does not load the helper snippets. Inspect or implement that reviewed bridge explicitly.
- The exported `CODEX_AGENT_ENV_SOURCED` guard can be inherited by child shells, while ordinary shell functions are not inherited. A marker-only clean-shell check is not proof of a fully isolated environment.
- The startup regression example checks helper presence rather than behavior. Its multi-file `zsh -n` invocation does not independently parse every supplied path; check each file separately when adopting the examples.
- Node, Homebrew, pnpm, editor, and helper paths are illustrative installation choices. Use supported installed toolchain versions and preserve existing local configuration.

## zsh/.zprofile

```zsh
# Login-shell setup for zsh.
# Codex and similar agents commonly execute commands via `zsh -lc`, which reads
# this file but not .zshrc.

[[ -r "$ZDOTDIR/codex-env.zsh" ]] && source "$ZDOTDIR/codex-env.zsh"
```

## zsh/.zshenv

```zsh
# Bootstrap ZDOTDIR for XDG-compliant zsh config
export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh"
[[ -f "$ZDOTDIR/.zshenv" ]] && source "$ZDOTDIR/.zshenv"

# Cargo (Rust)
[[ -r "$HOME/.cargo/env" ]] && source "$HOME/.cargo/env" >/dev/null 2>&1
```

## zsh/codex-env.zsh

```zsh
# =============================================================================
# Codex / Agent-Safe Shell Bootstrap
# =============================================================================
# Loaded by $ZDOTDIR/.zprofile so non-interactive login shells (`zsh -lc`) get
# the same tool paths and selected helper functions as interactive terminals.
#
# Keep this file free of prompt, completion, keybinding, and tty-only setup.
# Interactive-only config belongs in .zshrc.
# =============================================================================

[[ -n "${CODEX_AGENT_ENV_SOURCED:-}" ]] && return 0
export CODEX_AGENT_ENV_SOURCED=1

export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
export ZDOTDIR="${ZDOTDIR:-$XDG_CONFIG_HOME/zsh}"

# Homebrew shellenv is non-interactive and fills in HOMEBREW_* metadata.
[[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)"

# Small, declarative modules that are safe for non-interactive shells.
for _codex_env_file in \
  "$ZDOTDIR/conf.d/00-path.zsh" \
  "$ZDOTDIR/local.zsh"
do
  [[ -r "$_codex_env_file" ]] && source "$_codex_env_file"
done
unset _codex_env_file

# Tool-specific environment files that only export paths/vars.
[[ -r "$HOME/.atuin/bin/env" ]] && source "$HOME/.atuin/bin/env" >/dev/null 2>&1
[[ -r "$HOME/.cargo/env" ]] && source "$HOME/.cargo/env" >/dev/null 2>&1

export CLAUDE_ENV_FILE="${CLAUDE_ENV_FILE:-$HOME/.claude/shell-init.sh}"

# mdflow agent paths without loading the full interactive .zshrc.
typeset -U path
path=("$HOME/.mdflow" $path)
export PATH="${(j/:/)path}"

_codex_mdflow_path_refresh() {
  PATH=$(print -r -- "$PATH" \
    | tr ':' '\n' \
    | grep -vE '^(/[^/]+){4,}/\.mdflow$' \
    | tr '\n' ':' \
    | sed 's/:$//')

  [[ -d ".mdflow" ]] && export PATH="$PWD/.mdflow:$PATH"
  typeset -U path
  export PATH="${(j/:/)path}"
}

_codex_mdflow_path_refresh

if command -v mdflow >/dev/null 2>&1; then
  md() {
    command mdflow "$@"
  }
fi

if command -v zoxide >/dev/null 2>&1; then
  eval "$(zoxide init zsh --no-cmd)"

  j() {
    __zoxide_z "$@"
  }

  z() {
    __zoxide_zi "$@"
  }
fi
```

## zsh/conf.d/00-path.zsh

```zsh
# --- Module: PATH Plumbing (00-path.zsh) -------------------------------------
# Deterministic PATH/environment setup for shell startup.
# Machine-specific overrides belong in `local.zsh`.
#
# --- DSL Vocabulary -----------------------------------------------------------
# Functions: (none; declarative module)
# Verbs: export, prepend, deduplicate

# --- Path De-duplication ------------------------------------------------------
typeset -U path

# --- Configurable Defaults ----------------------------------------------------
# Override these defaults in `local.zsh` when needed.
: "${NODE_VERSION:=23.6.1}"
: "${HOMEBREW_PREFIX:=/opt/homebrew}"

# --- Common Home Directories --------------------------------------------------
export ZSH="${ZSH:-$HOME/.oh-my-zsh}"
export PNPM_HOME="${PNPM_HOME:-$HOME/Library/pnpm}"
export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"

# --- Warning Suppression ------------------------------------------------------
export PYTHONWARNINGS=ignore::DeprecationWarning

# --- PATH Assembly ------------------------------------------------------------
# Ordering is intentional: toolchain bins first, then inherited PATH entries.
path=(
  # Node, pnpm, and bun (highest priority).
  "$PNPM_HOME"
  "$HOME/Library/pnpm/nodejs/${NODE_VERSION}/bin"
  "$BUN_INSTALL/bin"

  # Homebrew and system binaries.
  "$HOMEBREW_PREFIX/opt/trash/bin"  # Keg-only formula path.
  "$HOMEBREW_PREFIX/bin"
  /usr/local/bin
  /usr/bin
  /bin

  # User tool directories.
  "$HOME/.config/agents"
  "$HOME/.local/bin"
  "$HOME/.ma"

  # Existing PATH entries.
  $path
)

# --- PATH Export --------------------------------------------------------------
export PATH="${(j/:/)path}"

# --- PNPM Precedence Guard ----------------------------------------------------
# Prepend `PNPM_HOME` when absent so pnpm shims stay highest-priority.
case ":$PATH:" in
  *":$PNPM_HOME:"*) ;;
  *) export PATH="$PNPM_HOME:$PATH" ;;
esac
```

## zsh/conf.d/40-ai.zsh

```zsh
# Workshop-safe AI helper loader.
# This file intentionally sources focused snippets instead of copying a full
# private shell config.

local _workshop_zsh_dir="${0:A:h:h}"

for _workshop_fn_file in \
  "$_workshop_zsh_dir/functions/codex-launch-and-prompt-builder.zsh" \
  "$_workshop_zsh_dir/functions/shell-introspection.zsh" \
  "$_workshop_zsh_dir/functions/fusion-fix.zsh" \
  "$_workshop_zsh_dir/functions/orchestration-helpers.zsh" \
  "$_workshop_zsh_dir/functions/script-kit-process-helpers.zsh"
do
  [[ -r "$_workshop_fn_file" ]] && source "$_workshop_fn_file"
done

unset _workshop_fn_file _workshop_zsh_dir
```

## zsh/conf.d/47-ai-fix.zsh

```zsh
# Backward-compatible entrypoint for the focused workshop snippet.
source "${0:A:h:h}/functions/fusion-fix.zsh"
```

## zsh/examples/codex-config-shell-environment-policy.toml

```toml
# Public shape only. Merge into your real ~/.codex/config.toml when you want
# Codex tool shells to receive the marker.

[shell_environment_policy.set]
CODEX_LOAD_ZSH_DSL = "1"
```

## zsh/examples/local.zsh.example

```zsh
# Machine-local overrides.
#
# Keep this file safe for non-interactive shells if it is sourced by
# `codex-env.zsh`.
#
# Do not commit real API keys, tokens, private endpoints, or machine-specific
# secrets. Use secret-manager helpers that resolve values at command execution
# time, and avoid printing secret values during startup.

# Example: add a local tool directory to PATH.
typeset -U path
path=("$HOME/.local/bin" $path)
export PATH="${(j/:/)path}"

# Example: command wrapper that resolves a secret only for the invoked command.
# with_example_provider() {
#   EXAMPLE_API_KEY="$(op item get EXAMPLE_API_KEY --fields credential --reveal)" "$@"
# }
```

## zsh/tests/startup-regression.zsh

```zsh
#!/usr/bin/env zsh
# Public startup regression check for the bundled workshop zsh files.

set -euo pipefail

fail() {
  print -u2 -- "FAIL: $1"
  exit 1
}

ROOT="${0:A:h:h}"

zsh -n \
  "$ROOT/.zshenv" \
  "$ROOT/.zprofile" \
  "$ROOT/codex-env.zsh" \
  "$ROOT/conf.d/00-path.zsh" \
  "$ROOT/conf.d/40-ai.zsh" \
  "$ROOT/conf.d/47-ai-fix.zsh" \
  "$ROOT"/functions/*.zsh || fail "syntax check failed"

out="$(
  cd "$ROOT:h"
  zsh -lc 'source ./zsh/conf.d/40-ai.zsh; for name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do printf "%s:%s\n" "$name" "$(whence -w "$name" 2>/dev/null || echo MISSING)"; done'
)"

for name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do
  [[ "$out" == *"$name:$name: function"* ]] || fail "missing bundled helper: $name"
done

print -- "ok: bundled zsh startup regression"
```


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