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/modules/codex-cli.nix
• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/

Destination	Source	Managed by
~/.codex/config.toml	Generated by activation script	codex-cli.nix
~/.codex/AGENTS.md	nix/home-manager/agents/AGENTS.md	codex-cli.nix
~/.codex/rules/	nix/home-manager/agents/rules/	codex-cli.nix
~/.codex/skills/	Multiple flake inputs + local	agent-skills.nix
MCP servers	nix/home-manager/modules/mcp-servers.nix	codex-cli.nix

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.

To update settings, edit nix/home-manager/modules/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=$(mkoutput --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
5. 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

Category	Examples
Model	model, model_reasoning, model_reasoning_effort
Behavior	approval_mode, sandbox, network_access
Display	notify, tui.notifications_method
Shell	shell_environment_commands
History	history, project_doc_max_bytes
Features	features.skills, features.web_search_request
Disable	disable_response_storage, hide_agent_*
Analytics	analytics.enabled, feedback.enabled

6. 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)

7. 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?

8. Optimization Tracking

Last reviewed Codex CLI version: v0.113.0 (2026-03-11)

8.1. Applied Optimizations

• AGENTS.md symlinked to CLAUDE.md (shared persona)
• skills/ symlinked to Claude Code skills
• config.common.toml for shared settings
• model_auto_compact_token_limit = builtins.floor (codexContextWindow * 0.7) autocompact at 70% (190,400 tokens for gpt-5.x 272k window)

8.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.)
• Review tui.notifications_method config option (added in v0.93.0)
• Plan mode (/plan) - now stable and enabled by default (v0.94.0)
• Review smart approvals default behavior (enabled in v0.93.0)
• personality setting - now stable (default: "friendly"); consider setting explicitly or using personality = "pragmatic" (v0.94.0)
• AfterToolUse hook - new hook event for post-tool automation (v0.99.0)
• command_attribution = "disable" - co-author attribution disabled (v0.103.0)
• approval_policy: on-failure - deprecated; review if used (v0.102.0)
• log_dir config - redirect logs to custom directory (v0.97.0)

8.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

8.4. Version Notes

• 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

9. Response Format (CHANGELOG)

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

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

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

## 改善
- [改善内容]

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

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

10. 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

11. Reference Links

• Codex CLI: https://github.com/openai/codex