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
.zshenvforwards to$ZDOTDIR/.zshenv; do not install the same forwarding file at both locations. - The supplied bootstrap does not implement the
CODEX_LOAD_ZSH_DSLopt-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_SOURCEDguard 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 -ninvocation 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"