Navigate the agent-safe shell file set

Explains the zsh environment and helper files, non-interactive-shell safety practices, and commands for checking tool paths and helper availability.

These files support Section 2, "Loading ZSH Env Into Codex."

They demonstrate a common Mac/zsh setup where Codex tool shells can see the same safe toolchain paths and selected helper functions without sourcing a full interactive .zshrc.

Included Files

.zshenv
.zprofile
codex-env.zsh
conf.d/00-path.zsh
conf.d/40-ai.zsh
conf.d/47-ai-fix.zsh
functions/codex-launch-and-prompt-builder.zsh
functions/shell-introspection.zsh
functions/fusion-fix.zsh
functions/orchestration-helpers.zsh
functions/script-kit-process-helpers.zsh
tests/startup-regression.zsh
examples/local.zsh.example
examples/codex-config-shell-environment-policy.toml

What Each File Teaches

File Purpose
.zshenv Sets XDG paths and ZDOTDIR; optionally loads selected DSL files when CODEX_LOAD_ZSH_DSL is present
.zprofile Login-shell bridge for zsh -lc
codex-env.zsh Agent-safe environment bootstrap for non-interactive shells
conf.d/00-path.zsh Deterministic PATH assembly
conf.d/40-ai.zsh Small loader for focused workshop helper snippets
conf.d/47-ai-fix.zsh Example workflow helper function
functions/codex-launch-and-prompt-builder.zsh x, xi, xfl, xfc, and Prompt Builder handoff helpers
functions/shell-introspection.zsh funclist, funcwhere, and funced
functions/fusion-fix.zsh Fusion-first fix helper
functions/orchestration-helpers.zsh muxai and reviewed lazy-loader patterns
functions/script-kit-process-helpers.zsh Process cleanup helper examples
tests/startup-regression.zsh Startup behavior checks
examples/local.zsh.example Public shape for machine-local overrides
examples/codex-config-shell-environment-policy.toml Public shape for Codex env policy

Safety Notes

  • Do not source a full .zshrc from agent shells.
  • Do not paste full env output into chats or handouts.
  • Keep prompt, completion, keybindings, fuzzy finders, and terminal UI in interactive startup only.
  • Prefer executable wrappers for helper entrypoints that must work outside zsh.
  • Treat CODEX_LOAD_ZSH_DSL as a local marker, not a Codex built-in.

Core Confirmation Commands

zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'
CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x 2>/dev/null || echo x:not-loaded; type x 2>/dev/null || true'
zsh -ic 'functions xi' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'
zsh -lc 'source ./zsh/conf.d/40-ai.zsh; whence -w x xi xfl xfc p-f p-c funcwhere muxai fix'

Operational boundaries

  • The file-purpose table describes the intended startup shape. The supplied .zshenv does not itself implement the optional DSL loader; review the practical setup prompt and actual local startup chain.

Source references