codex-config-optimizer（Codex 配置优化器）

Codex CLI Optimizer Skill

Rules and tracking for Codex CLI configuration optimization.

1. Config File Location

Config is managed declaratively via Nix (programs.codex home-manager module).

Source of truth:

• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/codex-cli.nix
• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/

2. Config Management

Static settings (model, analytics, features, MCP servers) are defined as Nix attributes in codex-cli.nix. Trusted projects are discovered dynamically by fd at home-manager switch time and appended to config.toml.

Hooks are also declared in codex-cli.nix; their runtime scripts live under nix/home-manager/agents/scripts/codex-* and are materialized into ~/.codex/scripts/ at switch time.

To update settings, edit nix/home-manager/agents/codex-cli.nix and rebuild.

3. Fetch Releases

3.1. Detect Local Version

Always detect the installed version first:

codex --version

This returns the locally installed version (e.g. codex-cli 0.113.0). All release analysis MUST be scoped to this version and below. Do NOT report features or changes from versions newer than the local install.

3.2. Fetch from GitHub

FILE=$(mkmd --dir tmp --label output)
gh api repos/openai/codex/releases --jq '.[0:10]' > "$FILE"

Then extract entries up to and including the local version using:

jq '.[] | select(.tag_name == "rust-v<LOCAL_VERSION>") | {tag_name, body}' "$FILE"

4. CHANGELOG Operations

IMPORTANT: All operations below are scoped to the locally installed version. Ignore any release entries for versions newer than codex --version.

4.1. Latest Release Summary

1. Detect local version with codex --version
2. Fetch releases using the command above
3. Extract the rust-v<local-version> release entry (not the first entry)
4. Categorize changes into:

- New features (Added) - Bug fixes (Fixed) - Improvements (Improved/Changed) - Breaking changes

1. Present in Japanese with brief explanations

4.2. Version Diff

1. Detect local version with codex --version
2. Ask user for start version (end version defaults to local version)
3. Extract all releases between start and local version (inclusive)
4. Summarize cumulative changes
5. Highlight breaking changes and deprecations

4.3. Breaking Changes Detection

1. Detect local version with codex --version
2. Search releases up to local version for: breaking, removed, deprecated, changed (behavior changes)
3. List affected commands and options
4. Provide migration guidance

5. Settings Categories

6. Hooks Guidance

• YOU MUST: Enable hooks with features.codex_hooks = true before relying on any hooks.json behavior
• YOU MUST: Keep Codex home-level hooks in nix/home-manager/agents/codex-cli.nix unless there is a deliberate repo-local override need
• YOU MUST: Keep Codex hook scripts under nix/home-manager/agents/scripts/codex-*
• YOU MUST: Reuse denied-bash-commands.nix as the SSOT for Bash deny policy instead of hand-maintaining separate Codex-only command lists
• YOU MUST: Keep shared Bash deny justifications repair-oriented so the rejection tells the agent what to do next, not just what was blocked
• YOU MUST: Treat Codex PreToolUse and PostToolUse as Bash-only today
• YOU MUST: Keep PostToolUse Bash hooks feedback-only; the command already ran, so use them for concise remediation rather than fake enforcement
• NEVER: Claim Codex currently intercepts Write|Edit|NotebookEdit; those matcher examples are valid regex but do not match current Codex runtime
• NEVER: Rely on unsupported permissionDecision: "ask" / "allow", updatedInput, or additionalContext fields for PreToolUse; the current runtime parses them but fails open
• NOTE: Official docs say SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, and Stop are the supported current events
• NOTE: Official docs say matching hooks from multiple hooks.json files all run, and matching command hooks for the same event launch concurrently
• NOTE: Stop is the closest current Codex equivalent to Claude PreCompact; use it for lightweight handoff persistence, not as proof of full parity

7. AGENTS.md Design Guidelines

• YOU MUST: Focus only on persona and core guidelines
• YOU MUST: Keep instructions compatible with both Claude Code and Codex CLI
• NEVER: Include tool-specific syntax (e.g., Claude Code's TodoWrite)

8. Optimization Checklist

Check the following when editing AGENTS.md or config.toml:

• Is the persona definition concise?
• Are basic rules truly needed at all times?
• Can detailed explanations be moved to skills/?
• Is config.toml using appropriate approval_mode?
• Are shared Bash deny messages phrased as safe next steps, not only denials?
• Are Codex hook limitations documented honestly (Bash-only pre/post tool)?
• Is PostToolUse scoped to deterministic Bash feedback, not enforcement?
• Is hook state split correctly between hooks.json and scripts/codex-*?

9. Optimization Tracking

Last reviewed Codex CLI version: v0.117.0 (2026-03-30)

9.1. Applied Optimizations

• AGENTS.md generated from shared AGENTS.md + inlined rule markdown
• skills/ symlinked to Claude Code skills
• default.rules generated from denied Bash policy
• Home-level Codex hooks enabled for UserPromptSubmit, SessionStart, PreToolUse (Bash only), PostToolUse (Bash only), and Stop
• Shared deny-bash patterns reused by both Claude Code and Codex CLI hooks
• Shared deny-bash justifications upgraded from bare denials to repair guidance for both Claude Code and Codex CLI
• Codex UserPromptSubmit now carries time, role, cwd, and git context
• Lightweight Codex handoff persistence via Stop + SessionStart
• model_auto_compact_token_limit = builtins.floor (codexContextWindow * 0.7) autocompact at 70% (190,400 tokens for gpt-5.x 272k window)
• tui.terminal_title = [] disables Codex terminal-title writes so tmux pane_title stays reserved for role identity (v0.117.0)

9.2. Pending Considerations

• Create prompts/ symlink to ../claude/commands/ if needed
• Create generate-config.sh for automated config.toml generation
• Evaluate MCP server integration (AWS docs MCP etc.)
• Plan mode (/plan) - now stable and enabled by default (v0.94.0)
• command_attribution = "disable" - co-author attribution disabled (v0.103.0)
• PostToolUse Bash feedback heuristics - keep scope narrow and deterministic as new repo failure patterns repeat
• code_mode experimental feature - isolated coding workflow; watch for stabilization (v0.114.0)
• Disable bundled system skills config switch - useful if custom skills suffice for leaner sessions (v0.114.0)
• Permission profile config language - split filesystem/network sandbox policies for finer control in config.toml (v0.113.0)
• Subagent support - multi-agent feature stabilized (v0.115.0);.toml agents auto-generated from subagents/*.md at Nix build time (codex-cli.nix)
• openai_base_url config override - custom API endpoint (v0.115.0)
• Smart Approvals guardian - route review requests through guardian subagent for reduced approval friction (v0.115.0)

9.3. Not Adopting

• personality setting - keep default ("friendly"); no benefit from changing
• log_dir config - default log location is fine
• tui.notifications_method - keep default
• CLAUDE_CODE_DISABLE_CRON env - N/A for Codex CLI
• approval_policy: on-failure - deprecated (v0.102.0); not used in config
• PreToolUse / PostToolUse matcher patterns like Write|Edit - current Codex runtime only emits Bash, so these configs are misleading today
• permissionDecision: "ask" / "allow" and updatedInput in PreToolUse - current runtime parses them but does not enforce them
• PostToolUse decision/block semantics for Bash repair hooks - keep these feedback-only so Codex still sees the raw command result
• AfterToolUse hook - superseded by documented hooks engine
• smart_approvals - keep default behavior (v0.93.0)

9.4. Version Notes

• v0.117.0: /title terminal-title picker now works in both classic and app-server TUI, plugins become a first-class workflow, app-server TUI is now enabled by default, and legacy artifact, read_file, and grep_files handlers were removed
• v0.116.0: Local installed version at review time; official hooks docs still mark hooks as experimental and document current event support/limits at https://developers.openai.com/codex/hooks
• v0.115.0: Full-resolution image inspection via view_image, js_repl gains codex.cwd/codex.homeDir with cross-cell persistence, realtime WebSocket transcription mode + v2 handoff, v2 app-server filesystem RPCs with Python SDK, Smart Approvals guardian subagent for review routing, tool-search via Responses API with fallback, multi-agent feature stabilized, wait_agent tool rename, bubblewrap default Linux sandbox, openai_base_url config override
• v0.114.0: Experimental code mode (isolated coding), hooks engine (SessionStart/Stop), health endpoints (/readyz//healthz) for app-server WebSocket, config to disable bundled system skills, handoff transcript context for turn continuity, $ mention picker with category labels, Linux tmux segfault fix, approval persistence across turns, Python SDK v2 schema foundation
• v0.113.0: request_permissions tool (runtime permission requests), plugin marketplace + curated discovery + uninstall, app-server streaming exec with TTY/PTY, web search full tool config, permission profile config language, image gen saves to cwd, SQLite DB for logs, winget auto-update
• v0.112.0: @plugin mentions for direct plugin reference, permission profiles merged into per-turn sandbox, JS REPL binding persistence fix, SIGTERM graceful shutdown, bubblewrap userns hardening, macOS Seatbelt improvements
• v0.111.0: Fast mode enabled by default, TUI shows Fast/Standard mode, js_repl can import local .js/.mjs files, plugins reported to model at session start, app-server v2 MCP elicitation as structured request/response
• v0.110.0: Plugin system (skills/MCP/app connectors from config or marketplace), persisted /fast toggle, multi-agent TUI flow with approval prompts, workspace-scoped memory writes, Windows installer
• v0.107.0: Fork thread into sub-agents, realtime voice device selection, multimodal custom tool output, memories configurable (codex debug clear-memories)
• v0.104.0: WS_PROXY/WSS_PROXY env for websocket proxying, ConfigChange hook from app-server, command approval ID plumbing
• v0.103.0: Commit co-author attribution via command_attribution config, richer app details in listings
• v0.102.0: Unified permissions flow with TUI history, slash command to grant sandbox read access, customizable multi-agent roles, model/rerouted notification, approval_policy: on-failure deprecated
• v0.101.0: Bug fixes for memory and model resolution
• v0.100.0: Experimental JS REPL runtime, memory slash commands (/m_update, /m_drop), ReadOnlyAccess sandbox policy, AfterToolUse hook
• v0.99.0: /statusline command for TUI footer config, shell commands no longer interrupt in-flight turns, GIF/WebP image support, AfterToolUse hook added, security fix (RUSTSEC-2026-0009)
• v0.98.0: GPT-5.3-Codex model introduced, steer mode stable by default (Enter sends, Tab queues)
• v0.97.0: "Allow and remember" for MCP/App tools, live skill updates, /debug-config slash command, configurable log_dir
• v0.96.0: unified_exec enabled on all non-Windows platforms
• v0.95.0: ~/.agents/skills personal skill loading, /plan accepts args and images, parallel shell tools, CODEX_THREAD_ID env injected
• v0.94.0: Plan mode enabled by default, personality config stable (default: friendly), skills from .agents/skills

10. Response Format (CHANGELOG)

# Codex CLI vX.X.X 更新内容

## 新機能
- [機能名]: [説明]

## バグ修正
- [修正内容]

## 改善
- [改善内容]

## 破壊的変更
- [影響を受ける機能と移行方法]

---
Source: https://github.com/openai/codex/releases

11. Important Notes

• Codex CLI changelog is on the releases page, not CHANGELOG.md
• Use GitHub releases API to fetch release notes
• Always specify the version being referenced
• Link to official release page when available

12. Reference Links

• Codex CLI: https://github.com/openai/codex
• Codex hooks docs: https://developers.openai.com/codex/hooks