Codex Agent

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

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:

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