Agent-safe shell startup file examples

Complete example startup files, PATH assembly, safe local overrides, environment-marker configuration, and startup checks, with explicit gaps and installation boundaries.

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

# 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

# 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

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

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

# 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

# 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

# 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

# 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

#!/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"

Source references