---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-shell-file-map"
title: "Navigate the agent-safe shell file set"
---

# Navigate the agent-safe shell file set

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

```text
.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

```bash
zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'
```

```bash
CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x 2>/dev/null || echo x:not-loaded; type x 2>/dev/null || true'
```

```bash
zsh -ic 'functions xi' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'
```

```bash
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.

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
