codex-exec — Claude Code command: what it does, how to install
codex-exec runs Codex CLI tasks directly inside Claude Code sessions. It applies proper sandboxing modes, reasoning flags, and selects between GPT-5 models.
MIT ★ 907 updated 2025-11-12
.claude/commands/codex-exec.mdWhat codex-exec does
This command wraps the Codex CLI to run smoothly inside Claude Code environments. Plain codex calls fail inside non-interactive shells with a stdout error, so codex-exec forces the codex exec syntax with model_reasoning_effort set to high and git repository checks disabled.
It handles four modes. Analysis runs read-only checks without modifying files, edit applies code changes using --full-auto, search enables web retrieval for external docs, and resume restores the previous session context. By default, coding edits route to GPT-5-Codex while analysis and search use general GPT-5.
The system must have the Codex CLI binary already installed in PATH; without it, commands fail immediately.
What it helps with
- inspect code for security issues in a read-only sandbox
- refactor code files and generate tests automatically
- query external web documentation through Codex search
- restore context from the previous Codex session
Example prompts for the agent
- /codex-exec analysis "check auth.py for SQL injection vulnerabilities"
- /codex-exec edit "refactor database.py to use connection pooling"
- /codex-exec resume
How to install codex-exec
Manually: put the files in place
.claude/commands/codex-exec.mdCall it with /codex-exec. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/codex-exec.mdCall it with /prompts:codex-exec. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/codex-exec.prompt.mdManually: put the files in place
.gemini/commands/codex-exec.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about codex-exec
How to install codex-exec in Claude Code?
Save the command file to .claude/commands/codex-exec.md in your project repository.
What does codex-exec do?
It forwards developer instructions to the Codex CLI via codex exec, configuring sandbox permissions and switching between GPT-5 and GPT-5-Codex.
Why does it use codex exec instead of plain codex?
Running standard codex inside Claude Code triggers a stdout is not a terminal error, whereas codex exec handles non-terminal execution properly.
Source text
codex-exec.md · MIT
# /codex-exec - Execute Codex CLI Commands **Easy wrapper for running Codex CLI commands from Claude Code with proper syntax.** --- ## Usage ``` /codex-exec [analysis|edit|search|resume] "your task" /codex-exec --model [gpt-5|gpt-5-codex] "your task" /codex-exec --help ``` --- ## What This Command Does **Executes Codex CLI commands with**: - ✅ Correct syntax (always uses `codex exec`) - ✅ Intelligent model selection - ✅ Appropriate sandbox modes - ✅ High reasoning effort - ✅ Error handling **CRITICAL**: Always uses `codex exec` not plain `codex` (required for Claude Code environment) --- ## Command Types ### Analysis (Read-Only) Safe code analysis without modifications. **Usage**: ``` /codex-exec analysis "analyze security vulnerabilities" ``` **Executes**: ```bash codex exec -m gpt-5 -s read-only \ -c model_reasoning_effort=high \ --skip-git-repo-check \ "analyze security vulnerabilities" ``` **Use for**: - Code review - Security analysis - Architecture review - Documentation reading - Performance analysis --- ### Edit (Workspace Write) Code editing and file modifications. **Usage**: ``` /codex-exec edit "refactor main.py for async patterns" ``` **Executes**: ```bash codex exec -m gpt-5-codex -s workspace-write \ -c model_reasoning_effort=high \ --full-auto \ --skip-git-repo-check \ "refactor main.py for async patterns" ``` **Use for**: - Code refactoring - Bug fixes - Feature implementation - Test generation - Documentation updates --- ### Search (Web Search Enabled) Tasks requiring latest information from the web. **Usage**: ``` /codex-exec search "research latest Python async patterns" ``` **Executes**: ```bash codex exec -m gpt-5 -s read-only \ -c model_reasoning_effort=high \ --search \ --skip-git-repo-check \ "research latest Python async patterns" ``` **Use for**: - Technology research - Best practices lookup - Library comparisons - Latest trends - Documentation lookup --- ### Resume (Continue Session) Resume previous Codex session. **Usage**: ``` /codex-exec resume ``` **Executes**: ```bash codex exec resume --last ``` **Use for**: - Continuing previous work - Adding to prior analysis - Iterative development - Follow-up questions --- ## Model Selection ### GPT-5 (General Reasoning) **Default for**: Analysis, Search, General tasks **Best for**: - Architecture design - Code review - Documentation - Planning - Research **Characteristics**: - High reasoning capability - General-purpose - Best for non-coding tasks --- ### GPT-5-Codex (Code Specialized) **Default for**: Edit tasks **Best for**: - Code refactoring - Bug fixing - Feature implementation - Test generation - Code translation **Characteristics**: - Optimized for coding - Better at code editing - Specialized knowledge --- ## Examples ### Example 1: Security Analysis **User**: ``` /codex-exec analysis "analyze this codebase for security vulnerabilities" ``` **What happens**: 1. Uses GPT-5 (general reasoning) 2. Read-only mode (safe) 3. High reasoning effort 4. Analyzes entire codebase 5. Returns security report **Output**: ``` 🚀 Executing Codex CLI command... Security Analysis Report: - Found 3 SQL injection vulnerabilities - Missing CSRF protection on 2 endpoints - Weak password validation - Recommendations: [detailed fixes] ✅ Analysis complete ``` --- ### Example 2: Code Refactoring **User**: ``` /codex-exec edit "refactor database.py to use connection pooling" ``` **What happens**: 1. Uses GPT-5-Codex (code specialized) 2. Workspace-write mode (can modify files) 3. Full-auto enabled 4. Refactors database.py 5. Implements connection pooling **Output**: ``` 🚀 Executing Codex CLI command... Refactored database.py: - Added connection pool (max_connections=20) - Implemented context managers - Added retry logic - Updated all database calls - Added tests ✅ Refactoring complete Files modified: database.py, tests/test_database.py ``` --- ### Example 3: Research Task **User**: ``` /codex-exec search "compare FastAPI vs Flask for microservices" ``` **What happens**: 1. Uses GPT-5 with web search 2. Researches latest information 3. Compares frameworks 4. Provides recommendations **Output**: ``` 🚀 Executing Codex CLI command... Framework Comparison: FastAPI vs Flask FastAPI: + Modern async support + Automatic API documentation (OpenAPI) + Type hints and validation (Pydantic) + Better performance (async) - Smaller ecosystem - Less mature Flask: + Large ecosystem + Mature and stable + Flexible and minimal - Synchronous by default - Manual API documentation Recommendation: FastAPI for new microservices ✅ Research complete ``` --- ### Example 4: Continue Previous Work **User**: ``` /codex-exec resume ``` **What happens**: 1. Resumes last Codex session 2. Continues context from previous work 3. No need to repeat information **Output**: ``` 🚀 Resuming last Codex session... Continuing from: "refactor database.py" Ready to continue. What's next? ``` --- ## Advanced Usage ### Custom Model Selection ``` /codex-exec --model gpt-5 edit "task" ``` Forces GPT-5 instead of default GPT-5-Codex for edit tasks. --- ### Show Command Only (Dry Run) ``` /codex-exec --dry-run analysis "task" ``` Shows the command that would be executed without running it. **Output**: ``` Would execute: codex exec -m gpt-5 -s read-only \ -c model_reasoning_effort=high \ --skip-git-repo-check \ "task" ``` --- ## Troubleshooting ### Error: "Codex CLI not found" **Solution**: ```bash # Install Codex CLI which codex # Check if installed codex --version # Verify works ``` --- ### Error: "stdout is not a terminal" **Cause**: Using plain `codex` instead of `codex exec` **Solution**: This command automatically uses `codex exec` ✅ --- ### Task Times Out **Symptom**: Command runs for > 5 minutes and times out **Solution**: ``` # Break into smaller tasks /codex-exec analysis "analyze auth module only" # Instead of /codex-exec analysis "analyze entire codebase" ``` --- ### Wrong Model Used **Symptom**: Using GPT-5 for coding tasks (slow) **Solution**: ``` # Use edit for coding tasks (auto-uses gpt-5-codex) /codex-exec edit "implement feature" # Or force model /codex-exec --model gpt-5-codex "implement feature" ``` --- ## Best Practices ### 1. Choose Right Command Type | Task Type | Command | Why | |-----------|---------|-----| | Review code | `analysis` | Read-only, safe | | Fix bug | `edit` | Can modify files | | Research library | `search` | Web search enabled | | Continue work | `resume` | Maintains context | --- ### 2. Be Specific ✅ **GOOD**: ``` /codex-exec analysis "check auth.py for SQL injection vulnerabilities" ``` ❌ **VAGUE**: ``` /codex-exec analysis "check security" ``` --- ### 3. Use Appropriate Scope **For large codebases**: ``` # Break into modules /codex-exec analysis "analyze auth module security" /codex-exec analysis "analyze API module security" ``` **Not**: ``` # Too broad /codex-exec analysis "analyze entire 100K line codebase" ``` --- ### 4. Resume for Iterative Work ``` # First task /codex-exec analysis "review authentication" [Review results] # Continue /codex-exec resume → "Now check the authorization logic" ``` --- ## Comparison: Claude Code vs Codex CLI | Feature | Claude Code | /codex-exec (via Codex CLI) | |---------|-------------|----------------------------| | Model | Claude Sonnet | GPT-5 / GPT-5-Codex | | Context | 200K tokens | Varies | | Skills | Native support | Reference in prompts | | Agents | Native | Not applicable | | Reasoning | High | Configurable | | Persistence | Session-based | Session resumable | **Use Claude Code when**: - Working with Claude Skills - Using Claude Agents - Leveraging 200K context - Integrated workflow **Use /codex-exec when**: - Want GPT-5 perspective - Testing multiple approaches - Specific Codex features needed - Team uses both tools --- ## Integration with Bridge Skill Works seamlessly with codex-cli-bridge: ``` # 1. Generate AGENTS.md /sync-agents-md # 2. Reference in Codex command /codex-exec analysis "Using AGENTS.md, review project structure" # 3. Use skill documentation /codex-exec "Using skill at path/to/SKILL.md, implement feature" ``` --- ## Technical Details **Command Type**: Slash command wrapper **Skill Used**: codex-cli-bridge (codex_executor.py) **Python Module**: CodexExecutor class **Timeout**: 5 minutes (300 seconds) **Models**: GPT-5, GPT-5-Codex **Sandbox Modes**: read-only, workspace-write, danger-full-access --- ## Command Reference | Command | Model | Sandbox | Use Case | |---------|-------|---------|----------| | `/codex-exec analysis "task"` | gpt-5 | read-only | Safe analysis | | `/codex-exec edit "task"` | gpt-5-codex | workspace-write | Code editing | | `/codex-exec search "task"` | gpt-5 | read-only | Web research | | `/codex-exec resume` | Previous | Previous | Continue session | | `/codex-exec --model gpt-5 "task"` | gpt-5 | read-only | Force model | | `/codex-exec --dry-run "task"` | - | - | Show command | --- ## See Also - **`/sync-agents-md`**: Regenerate AGENTS.md - **codex-cli-bridge SKILL.md**: Complete skill documentation - **codex_executor.py**: Python implementation - **Codex CLI Docs**: https://github.com/openai/codex --- **Version**: 1.0.0 **Last Updated**: 2025-10-30 **Maintained For**: Easy Codex CLI execution from Claude Code --- **Execute Codex commands the right way!** 🚀
© alirezarezvani · MIT · alirezarezvani/claude-code-skill-factory