{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-file-map",
  "slug": "shell-file-map",
  "title": "Navigate the agent-safe shell file set",
  "summary": "Explains the zsh environment and helper files, non-interactive-shell safety practices, and commands for checking tool paths and helper availability.",
  "category": "Tools",
  "tags": [
    "zsh",
    "environment",
    "files"
  ],
  "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/README.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Included Files",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/What Each File Teaches",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Safety Notes",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Core Confirmation Commands",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 382,
  "url": "/topics/codex-shell-file-map/",
  "markdownUrl": "/markdown/codex-shell-file-map.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-file-map.json",
  "headings": [
    {
      "id": "included-files",
      "text": "Included Files",
      "level": 2
    },
    {
      "id": "what-each-file-teaches",
      "text": "What Each File Teaches",
      "level": 2
    },
    {
      "id": "safety-notes",
      "text": "Safety Notes",
      "level": 2
    },
    {
      "id": "core-confirmation-commands",
      "text": "Core Confirmation Commands",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Navigate the agent-safe shell file set\n\nThese files support Section 2, \"Loading ZSH Env Into Codex.\"\n\nThey 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`.\n\n## Included Files\n\n```text\n.zshenv\n.zprofile\ncodex-env.zsh\nconf.d/00-path.zsh\nconf.d/40-ai.zsh\nconf.d/47-ai-fix.zsh\nfunctions/codex-launch-and-prompt-builder.zsh\nfunctions/shell-introspection.zsh\nfunctions/fusion-fix.zsh\nfunctions/orchestration-helpers.zsh\nfunctions/script-kit-process-helpers.zsh\ntests/startup-regression.zsh\nexamples/local.zsh.example\nexamples/codex-config-shell-environment-policy.toml\n```\n\n## What Each File Teaches\n\n| File | Purpose |\n| --- | --- |\n| `.zshenv` | Sets XDG paths and `ZDOTDIR`; optionally loads selected DSL files when `CODEX_LOAD_ZSH_DSL` is present |\n| `.zprofile` | Login-shell bridge for `zsh -lc` |\n| `codex-env.zsh` | Agent-safe environment bootstrap for non-interactive shells |\n| `conf.d/00-path.zsh` | Deterministic PATH assembly |\n| `conf.d/40-ai.zsh` | Small loader for focused workshop helper snippets |\n| `conf.d/47-ai-fix.zsh` | Example workflow helper function |\n| `functions/codex-launch-and-prompt-builder.zsh` | `x`, `xi`, `xfl`, `xfc`, and Prompt Builder handoff helpers |\n| `functions/shell-introspection.zsh` | `funclist`, `funcwhere`, and `funced` |\n| `functions/fusion-fix.zsh` | Fusion-first `fix` helper |\n| `functions/orchestration-helpers.zsh` | `muxai` and reviewed lazy-loader patterns |\n| `functions/script-kit-process-helpers.zsh` | Process cleanup helper examples |\n| `tests/startup-regression.zsh` | Startup behavior checks |\n| `examples/local.zsh.example` | Public shape for machine-local overrides |\n| `examples/codex-config-shell-environment-policy.toml` | Public shape for Codex env policy |\n\n## Safety Notes\n\n- Do not source a full `.zshrc` from agent shells.\n- Do not paste full `env` output into chats or handouts.\n- Keep prompt, completion, keybindings, fuzzy finders, and terminal UI in interactive startup only.\n- Prefer executable wrappers for helper entrypoints that must work outside zsh.\n- Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in.\n\n## Core Confirmation Commands\n\n```bash\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x 2>/dev/null || echo x:not-loaded; type x 2>/dev/null || true'\n```\n\n```bash\nzsh -ic 'functions xi' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'\n```\n\n```bash\nzsh -lc 'source ./zsh/conf.d/40-ai.zsh; whence -w x xi xfl xfc p-f p-c funcwhere muxai fix'\n```\n\n## Operational boundaries\n\n- 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.\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/)"
}
