{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-startup-files",
  "slug": "shell-startup-files",
  "title": "Agent-safe shell startup file examples",
  "summary": "Complete example startup files, PATH assembly, safe local overrides, environment-marker configuration, and startup checks, with explicit gaps and installation boundaries.",
  "category": "Tools",
  "tags": [
    "zsh",
    "startup",
    "environment"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/.zprofile",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/.zshenv",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/codex-env.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/00-path.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/40-ai.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/47-ai-fix.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/examples/codex-config-shell-environment-policy.toml",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/examples/local.zsh.example",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/tests/startup-regression.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 992,
  "url": "/topics/codex-shell-startup-files/",
  "markdownUrl": "/markdown/codex-shell-startup-files.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-startup-files.json",
  "headings": [
    {
      "id": "safety-and-completeness-boundaries",
      "text": "Safety and completeness boundaries",
      "level": 2
    },
    {
      "id": "zsh-zprofile",
      "text": "zsh/.zprofile",
      "level": 2
    },
    {
      "id": "zsh-zshenv",
      "text": "zsh/.zshenv",
      "level": 2
    },
    {
      "id": "zsh-codex-env-zsh",
      "text": "zsh/codex-env.zsh",
      "level": 2
    },
    {
      "id": "zsh-conf-d-00-path-zsh",
      "text": "zsh/conf.d/00-path.zsh",
      "level": 2
    },
    {
      "id": "zsh-conf-d-40-ai-zsh",
      "text": "zsh/conf.d/40-ai.zsh",
      "level": 2
    },
    {
      "id": "zsh-conf-d-47-ai-fix-zsh",
      "text": "zsh/conf.d/47-ai-fix.zsh",
      "level": 2
    },
    {
      "id": "zsh-examples-codex-config-shell-environment-policy-toml",
      "text": "zsh/examples/codex-config-shell-environment-policy.toml",
      "level": 2
    },
    {
      "id": "zsh-examples-local-zsh-example",
      "text": "zsh/examples/local.zsh.example",
      "level": 2
    },
    {
      "id": "zsh-tests-startup-regression-zsh",
      "text": "zsh/tests/startup-regression.zsh",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Agent-safe shell startup file examples\n\nThese examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.\n\n## Safety and completeness boundaries\n\n- 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.\n- 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.\n- 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.\n- 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.\n- Node, Homebrew, pnpm, editor, and helper paths are illustrative installation choices. Use supported installed toolchain versions and preserve existing local configuration.\n\n## zsh/.zprofile\n\n```zsh\n# Login-shell setup for zsh.\n# Codex and similar agents commonly execute commands via `zsh -lc`, which reads\n# this file but not .zshrc.\n\n[[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n```\n\n## zsh/.zshenv\n\n```zsh\n# Bootstrap ZDOTDIR for XDG-compliant zsh config\nexport ZDOTDIR=\"${XDG_CONFIG_HOME:-$HOME/.config}/zsh\"\n[[ -f \"$ZDOTDIR/.zshenv\" ]] && source \"$ZDOTDIR/.zshenv\"\n\n# Cargo (Rust)\n[[ -r \"$HOME/.cargo/env\" ]] && source \"$HOME/.cargo/env\" >/dev/null 2>&1\n```\n\n## zsh/codex-env.zsh\n\n```zsh\n# =============================================================================\n# Codex / Agent-Safe Shell Bootstrap\n# =============================================================================\n# Loaded by $ZDOTDIR/.zprofile so non-interactive login shells (`zsh -lc`) get\n# the same tool paths and selected helper functions as interactive terminals.\n#\n# Keep this file free of prompt, completion, keybinding, and tty-only setup.\n# Interactive-only config belongs in .zshrc.\n# =============================================================================\n\n[[ -n \"${CODEX_AGENT_ENV_SOURCED:-}\" ]] && return 0\nexport CODEX_AGENT_ENV_SOURCED=1\n\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:-$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:-$HOME/.local/share}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:-$HOME/.cache}\"\nexport XDG_STATE_HOME=\"${XDG_STATE_HOME:-$HOME/.local/state}\"\nexport ZDOTDIR=\"${ZDOTDIR:-$XDG_CONFIG_HOME/zsh}\"\n\n# Homebrew shellenv is non-interactive and fills in HOMEBREW_* metadata.\n[[ -x /opt/homebrew/bin/brew ]] && eval \"$(/opt/homebrew/bin/brew shellenv)\"\n\n# Small, declarative modules that are safe for non-interactive shells.\nfor _codex_env_file in \\\n  \"$ZDOTDIR/conf.d/00-path.zsh\" \\\n  \"$ZDOTDIR/local.zsh\"\ndo\n  [[ -r \"$_codex_env_file\" ]] && source \"$_codex_env_file\"\ndone\nunset _codex_env_file\n\n# Tool-specific environment files that only export paths/vars.\n[[ -r \"$HOME/.atuin/bin/env\" ]] && source \"$HOME/.atuin/bin/env\" >/dev/null 2>&1\n[[ -r \"$HOME/.cargo/env\" ]] && source \"$HOME/.cargo/env\" >/dev/null 2>&1\n\nexport CLAUDE_ENV_FILE=\"${CLAUDE_ENV_FILE:-$HOME/.claude/shell-init.sh}\"\n\n# mdflow agent paths without loading the full interactive .zshrc.\ntypeset -U path\npath=(\"$HOME/.mdflow\" $path)\nexport PATH=\"${(j/:/)path}\"\n\n_codex_mdflow_path_refresh() {\n  PATH=$(print -r -- \"$PATH\" \\\n    | tr ':' '\\n' \\\n    | grep -vE '^(/[^/]+){4,}/\\.mdflow$' \\\n    | tr '\\n' ':' \\\n    | sed 's/:$//')\n\n  [[ -d \".mdflow\" ]] && export PATH=\"$PWD/.mdflow:$PATH\"\n  typeset -U path\n  export PATH=\"${(j/:/)path}\"\n}\n\n_codex_mdflow_path_refresh\n\nif command -v mdflow >/dev/null 2>&1; then\n  md() {\n    command mdflow \"$@\"\n  }\nfi\n\nif command -v zoxide >/dev/null 2>&1; then\n  eval \"$(zoxide init zsh --no-cmd)\"\n\n  j() {\n    __zoxide_z \"$@\"\n  }\n\n  z() {\n    __zoxide_zi \"$@\"\n  }\nfi\n```\n\n## zsh/conf.d/00-path.zsh\n\n```zsh\n# --- Module: PATH Plumbing (00-path.zsh) -------------------------------------\n# Deterministic PATH/environment setup for shell startup.\n# Machine-specific overrides belong in `local.zsh`.\n#\n# --- DSL Vocabulary -----------------------------------------------------------\n# Functions: (none; declarative module)\n# Verbs: export, prepend, deduplicate\n\n# --- Path De-duplication ------------------------------------------------------\ntypeset -U path\n\n# --- Configurable Defaults ----------------------------------------------------\n# Override these defaults in `local.zsh` when needed.\n: \"${NODE_VERSION:=23.6.1}\"\n: \"${HOMEBREW_PREFIX:=/opt/homebrew}\"\n\n# --- Common Home Directories --------------------------------------------------\nexport ZSH=\"${ZSH:-$HOME/.oh-my-zsh}\"\nexport PNPM_HOME=\"${PNPM_HOME:-$HOME/Library/pnpm}\"\nexport BUN_INSTALL=\"${BUN_INSTALL:-$HOME/.bun}\"\n\n# --- Warning Suppression ------------------------------------------------------\nexport PYTHONWARNINGS=ignore::DeprecationWarning\n\n# --- PATH Assembly ------------------------------------------------------------\n# Ordering is intentional: toolchain bins first, then inherited PATH entries.\npath=(\n  # Node, pnpm, and bun (highest priority).\n  \"$PNPM_HOME\"\n  \"$HOME/Library/pnpm/nodejs/${NODE_VERSION}/bin\"\n  \"$BUN_INSTALL/bin\"\n\n  # Homebrew and system binaries.\n  \"$HOMEBREW_PREFIX/opt/trash/bin\"  # Keg-only formula path.\n  \"$HOMEBREW_PREFIX/bin\"\n  /usr/local/bin\n  /usr/bin\n  /bin\n\n  # User tool directories.\n  \"$HOME/.config/agents\"\n  \"$HOME/.local/bin\"\n  \"$HOME/.ma\"\n\n  # Existing PATH entries.\n  $path\n)\n\n# --- PATH Export --------------------------------------------------------------\nexport PATH=\"${(j/:/)path}\"\n\n# --- PNPM Precedence Guard ----------------------------------------------------\n# Prepend `PNPM_HOME` when absent so pnpm shims stay highest-priority.\ncase \":$PATH:\" in\n  *\":$PNPM_HOME:\"*) ;;\n  *) export PATH=\"$PNPM_HOME:$PATH\" ;;\nesac\n```\n\n## zsh/conf.d/40-ai.zsh\n\n```zsh\n# Workshop-safe AI helper loader.\n# This file intentionally sources focused snippets instead of copying a full\n# private shell config.\n\nlocal _workshop_zsh_dir=\"${0:A:h:h}\"\n\nfor _workshop_fn_file in \\\n  \"$_workshop_zsh_dir/functions/codex-launch-and-prompt-builder.zsh\" \\\n  \"$_workshop_zsh_dir/functions/shell-introspection.zsh\" \\\n  \"$_workshop_zsh_dir/functions/fusion-fix.zsh\" \\\n  \"$_workshop_zsh_dir/functions/orchestration-helpers.zsh\" \\\n  \"$_workshop_zsh_dir/functions/script-kit-process-helpers.zsh\"\ndo\n  [[ -r \"$_workshop_fn_file\" ]] && source \"$_workshop_fn_file\"\ndone\n\nunset _workshop_fn_file _workshop_zsh_dir\n```\n\n## zsh/conf.d/47-ai-fix.zsh\n\n```zsh\n# Backward-compatible entrypoint for the focused workshop snippet.\nsource \"${0:A:h:h}/functions/fusion-fix.zsh\"\n```\n\n## zsh/examples/codex-config-shell-environment-policy.toml\n\n```toml\n# Public shape only. Merge into your real ~/.codex/config.toml when you want\n# Codex tool shells to receive the marker.\n\n[shell_environment_policy.set]\nCODEX_LOAD_ZSH_DSL = \"1\"\n```\n\n## zsh/examples/local.zsh.example\n\n```zsh\n# Machine-local overrides.\n#\n# Keep this file safe for non-interactive shells if it is sourced by\n# `codex-env.zsh`.\n#\n# Do not commit real API keys, tokens, private endpoints, or machine-specific\n# secrets. Use secret-manager helpers that resolve values at command execution\n# time, and avoid printing secret values during startup.\n\n# Example: add a local tool directory to PATH.\ntypeset -U path\npath=(\"$HOME/.local/bin\" $path)\nexport PATH=\"${(j/:/)path}\"\n\n# Example: command wrapper that resolves a secret only for the invoked command.\n# with_example_provider() {\n#   EXAMPLE_API_KEY=\"$(op item get EXAMPLE_API_KEY --fields credential --reveal)\" \"$@\"\n# }\n```\n\n## zsh/tests/startup-regression.zsh\n\n```zsh\n#!/usr/bin/env zsh\n# Public startup regression check for the bundled workshop zsh files.\n\nset -euo pipefail\n\nfail() {\n  print -u2 -- \"FAIL: $1\"\n  exit 1\n}\n\nROOT=\"${0:A:h:h}\"\n\nzsh -n \\\n  \"$ROOT/.zshenv\" \\\n  \"$ROOT/.zprofile\" \\\n  \"$ROOT/codex-env.zsh\" \\\n  \"$ROOT/conf.d/00-path.zsh\" \\\n  \"$ROOT/conf.d/40-ai.zsh\" \\\n  \"$ROOT/conf.d/47-ai-fix.zsh\" \\\n  \"$ROOT\"/functions/*.zsh || fail \"syntax check failed\"\n\nout=\"$(\n  cd \"$ROOT:h\"\n  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'\n)\"\n\nfor name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do\n  [[ \"$out\" == *\"$name:$name: function\"* ]] || fail \"missing bundled helper: $name\"\ndone\n\nprint -- \"ok: bundled zsh startup regression\"\n```\n\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
