Codex CLI Optimizer Skill Skill

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/

| Destination | Source | Managed by | | ---------------------- | ----------------------------------------------------- | -------------------------- | | ~/.codex/config.toml | Generated by activation script | codex-cli.nix | | ~/.codex/AGENTS.md | Generated from AGENTS.md + inlined rules/*.md | instruction-artifacts.nix | | ~/.codex/rules/ | Generated default.rules from denied Bash policy | codex-cli.nix | | ~/.codex/hooks.json | Generated hook config | codex-cli.nix | | ~/.codex/scripts/ | Symlinked codex-* scripts + shared deny patterns | codex-cli.nix | | ~/.codex/skills/ | Multiple flake inputs + local | agent-skills.nix | | MCP servers | nix/home-manager/agents/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.

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

Detect local version with codex --version
Fetch releases using the command above
Extract the rust-v<local-version> release entry (not the first entry)
Categorize changes into:
- New features (Added)
- Bug fixes (Fixed)
- Improvements (Improved/Changed)
- Breaking changes
Present in Japanese with brief explanations

4.2. Version Diff

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

4.3. Breaking Changes Detection

Detect local version with codex --version
Search releases up to local version for: breaking, removed, deprecated, changed (behavior changes)
List affected commands and options
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 | | Hooks | features.codex_hooks, hooks.json, scripts/codex-* | | 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. 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

[x] AGENTS.md generated from shared AGENTS.md + inlined rule markdown
[x] skills/ symlinked to Claude Code skills
[x] default.rules generated from denied Bash policy
[x] Home-level Codex hooks enabled for UserPromptSubmit, SessionStart, PreToolUse (Bash only), PostToolUse (Bash only), and Stop
[x] Shared deny-bash patterns reused by both Claude Code and Codex CLI hooks
[x] Shared deny-bash justifications upgraded from bare denials to repair guidance for both Claude Code and Codex CLI
[x] Codex UserPromptSubmit now carries time, role, cwd, and git context
[x] Lightweight Codex handoff persistence via Stop + SessionStart
[x] model_auto_compact_token_limit = builtins.floor (codexContextWindow * 0.7) autocompact at 70% (190,400 tokens for gpt-5.x 272k window)
[x] 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.)
[x] Plan mode (/plan) - now stable and enabled by default (v0.94.0)
[x] 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)
[x] 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

Agent Skills: Codex CLI Optimizer Skill

Install this agent skill to your local

Skill Files