Skip to content

diegosouzapw/awesome-omni-skill / skills/ai-agents/codex-agent

codex-agent

Verified

Invoke OpenAI Codex CLI for coding and complex tasks. ALWAYS use the codex_agent_direct TOOL — NEVER exec codex directly. Direct codex exec opens an interactive TUI that hangs and gets killed. The tool handles non-interactive execution correctly.

Codex Agent — Direct Tool

CRITICAL: NEVER run exec codex ... directly. Running codex without the tool opens an interactive TUI that hangs and gets killed with signal 9. Always use the codex_agent_direct tool below.

Use your own model first. Only delegate to Codex when the user explicitly asks, or the task is large/multi-file.

Primary Method: codex_agent_direct Tool

The codex_agent_direct tool invokes Codex CLI non-interactively (codex exec) with structured JSON output. This is the preferred method for all Codex interactions.

codex_agent_direct(
  prompt: "Your detailed task description",
  workspace: "/path/to/project",    // optional, passed as --cd
  model: "gpt-4.1-mini",            // optional, default "gpt-4.1-mini"
  mode: "agent" | "plan" | "ask"    // optional, default "agent"
)

Modes

  • agent (default): Execute code changes and commands. Codex runs with auto approval — it reads, edits, and runs commands in the workspace. Use for "implement", "refactor", "fix" tasks.
  • plan: Plan before executing. Passes --plan to codex exec. Codex proposes a plan before making changes. Use when the user says "plan first", "design approach", or for large/ambiguous tasks.
  • ask: Read-only / suggest-only. Codex is set to suggest approval mode — it explains and proposes but does not auto-run. Use for "explain", "where is", "why does" — no edits.

When to Use

  • User explicitly asks for "Codex", "openai codex", or "use Codex"
  • Coding tasks: write, edit, refactor, review code
  • Complex multi-file operations: Codex understands full codebase context
  • Analysis: deep code analysis, dependency checking, architecture review
  • Task is large, multi-file, or benefits from GPT-5 Codex reasoning

Model Selection

ModelUse when
gpt-4.1-miniDefault — fast, capable, cost-effective
gpt-4.1Complex reasoning, large codebases
gpt-5.3-codexMaximum capability (requires ChatGPT Pro/Plus auth)

Output

The tool returns structured JSON:

  • output: Codex's text response (may include JSON transcript from --json flag)
  • exit_code: 0 for success
  • duration_ms: execution time
  • files_created: list of new file paths detected after the run
  • truncated: true if output was capped at 100KB

There Is No Fallback — Handle Errors Directly

DO NOT exec codex under any circumstances. Running codex or exec codex ... opens an interactive TUI that hangs forever and gets killed with signal 9. There is no safe direct exec fallback.

When the tool returns ok: false or an error:

  1. Read the error or output field — it contains the failure reason (e.g. "not a trusted directory", "model not found")
  2. Report it to the user directly — e.g. "Codex failed: [reason]. You may need to run codex interactively first to trust this directory."
  3. Do NOT retry with exec, sessions_spawn, process polling, or any other approach
  4. Do NOT start a background process and poll it

When the tool returns empty output:

Report to the user: "Codex returned no output. The workspace may not be a trusted git repo, or Codex may need re-authentication."

When output is raw JSONL:

The tool parses JSONL and returns clean text. If you still see raw {"type":...} JSON in the output, just summarize what you can see and tell the user the response format was unexpected.

Common errors and what to tell the user:

ErrorTell user
Not inside a trusted directoryRun codex interactively in the workspace first to trust it, or pass --skip-git-repo-check
model not supportedYour ChatGPT account uses gpt-5.3-codex — omit --model to use config default
stream disconnectedCodex authentication may have expired — run codex interactively to re-login
signal 9 / process killedThe codex TUI was opened instead of non-interactive exec — this means exec was called directly, which is forbidden

Prerequisites

  • Codex CLI installed: npm i -g @openai/codex
  • Authenticated: run codex once interactively to sign in with your ChatGPT account or API key
  • Verify: python3 plugin/scripts/codex_agent_direct.py --check

Project Config

The project includes .codex/config.toml with sensible defaults:

  • Model: gpt-4.1-mini
  • Approval: on-request (Codex asks before running commands)
  • Web search: cached

Override per-run with --model or --approval flags.

Do NOT

  • Do NOT run codex interactively from exec — it opens a TUI and hangs
  • Do NOT use codex without the exec subcommand for automation
  • Do NOT expose API keys in prompts or command arguments
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall