2026 Latest .codex Directory and Configuration Explained

2026 Codex .codex directory and config.toml explained. Global vs project settings, models, sandbox, profiles, and best practices.

“AI Disruption” Publication 9900 Subscriptions 20% Discount Offer Link.

---

I previously provided a systematic introduction to Claude Code’s .claude directory.

.claude Folder: From Chat to Engineering System

This time, I’ll continue by sharing a detailed breakdown of Codex’s .codex configuration files. This is based on the latest version of Codex, including explanations of the main configuration files, detailed field descriptions, and some of the configurations I am currently using myself.

In Codex, the .codex directory primarily serves two responsibilities:

1. Codex’s own local state directory
Default location: ~/.codex
Codex stores its local state under CODEX_HOME, which defaults to ~/.codex.

Common contents include config.toml, auth.json, history.jsonl, logs, and cache.

2. Project-level configuration directory
That is, .codex/config.toml inside the repository.

Codex searches for .codex/config.toml starting from the project root and moving up toward the current working directory. Configurations closer to the current directory have higher priority.

The main difference between the two:

~/.codex is Codex’s global workbench, while the .codex folder inside a project provides project-specific local configuration for Codex.

Recommended .codex Directory Structure

Here is the recommended structure for the new version’s local directory:

~/.codex/
├── config.toml              # Main user-level configuration
├── auth.json                # Login cache (appears when using file storage; sensitive file)
├── history.jsonl            # Command history (appears when history persistence is enabled)
├── log/                     # Codex log directory (default log location)
├── hooks.json               # User-level lifecycle hooks (optional)
├── themes/                  # TUI custom themes (optional)
├── model-catalogs/          # Custom model catalog files (optional, self-hosted)
└── state/cache/...          # Other caches or state files (may vary by version)

In this structure, only config.toml is the file you will edit most frequently.