/hone

Codex Config Schema

Purpose: Comprehensive reference for all Codex CLI configuration keys, default values, and recommended settings. Read when: Auditing ~/.codex/config.toml or proposing configuration changes. Last updated: 2026-03-12 (Codex CLI v0.114.0)

Config File Location

Primary: ~/.codex/config.toml

Core Settings

Policy Settings

TUI Settings

[tui]
status_line = ["model-with-reasoning", "context-remaining", "current-dir"]
theme = "catppuccin-mocha"
animations = true
show_tooltips = true
alternate_screen = "auto"
notifications = true
notification_method = "auto"

Status Line Items (verified against v0.114.0)

Note: IDs defined in PR #10546 that may not yet be implemented in v0.114.0: rate-limits, tokens, tokens-input, tokens-output, cwd. Use the /statusline command to check which items are actually available.

• null or [] hides the status line
• Can be configured interactively via the /statusline command

TUI Options

Custom Themes

Place .tmTheme files in $CODEX_HOME/themes/ to make them selectable via /theme.

Trust Levels

[projects."/path/to/project"]
trust_level = "trusted"      # full-auto allowed

Trust Level Audit Criteria

• Stale paths: Projects that no longer exist on disk
• Over-trust: Sensitive dirs (home, .ssh/, .aws/) marked as trusted
• Under-trust: Personal projects unnecessarily restricted
• Wildcard paths: Overly broad trust patterns
• External volumes: Removable/network paths that may not be mounted

Feature Flags

[features]
unified_exec = true
shell_snapshot = true
steer = true
apps = true
personality = true
multi_agent = true
prevent_idle_sleep = true

Feature flags evolve rapidly. Verify against the latest release notes.

History

[history]
persistence = "save-all"    # "save-all", "save-none", "ask"

MCP Server Configuration

[mcp_servers.server-name]
command = "/absolute/path/to/binary"
args = ["arg1", "arg2"]
env = { KEY = "value" }

MCP Audit Criteria

• Accessibility: Server binary exists and is executable
• Path: Use absolute paths to avoid PATH resolution issues
• Version: Server is up-to-date
• Necessity: Server is actively used
• Security: No secrets in plaintext args/env

Rules

# ~/.codex/rules/default.rules
prefix_rule(pattern=["git", "add"], decision="allow")
prefix_rule(pattern=["git", "commit", "-m"], decision="allow")

Rules Audit Criteria

• Overly specific: Individual command rules that should be generalized
• Redundant: Rules subsumed by broader patterns
• Missing: Common commands that lack allow rules

Other Configuration Files

Other Display Settings

Profiles

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

[profiles.review]
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"

Usage: codex --profile ci

Notice (Auto-managed)

[notice]
hide_xxx_migration_prompt = true

[notice.model_migrations]
"old-model" = "new-model"

A section auto-managed by Codex CLI. It's safe to manually remove stale migration prompts.

Version History

This schema should be refreshed when major Codex CLI versions are released.