Codex Agent

Prerequisites

1. Install Codex CLI:

   npm install -g @openai/codex

2. Ensure you have completed Codex login authentication (the first run of

   codex

   will guide you through login)
3. It is recommended to run in the target project directory, or explicitly pass

   -C /path/to/project

Usage Methods

Create a New Session

codex exec --json --sandbox workspace-write --skip-git-repo-check --model gpt-5.4 "Your task description"

{"type":"thread.started","thread_id":"019d32fc-..."}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"Response content"}}
{"type":"turn.completed","usage":{"input_tokens":46879,"cached_input_tokens":2432,"output_tokens":54}}

• Extract

  thread_id

  from the

  thread.started

  event for subsequent multi-turn conversations
• Extract

  text

  from the

  item.completed

  event (where

  item.type == "agent_message"

  ) as Codex's response
• Extract

  usage

  from

  turn.completed

  to record token consumption

stderr

stdout

{

stderr

Use stdin Pipe for Long Prompts

Reading additional input from stdin...

codex exec

-

codex exec --json --sandbox workspace-write --full-auto --model gpt-5.4 \
  --skip-git-repo-check - < /tmp/task-prompt.txt > /tmp/task-out.jsonl 2>&1

Resume a Session

codex exec resume --json --model gpt-5.4 "thread_id" "Follow-up question"

Resume the Most Recent Session (Shortcut)

codex exec resume --json --model gpt-5.4 --last "Follow-up question"

• --last

  only looks at the most recent session recorded in the current directory by default
• Add

  --all

  when you need to search across directories

⚠️

--ephemeral

: Non-recoverable Session

--ephemeral

~/.codex/sessions/

codex exec resume

--last

• One-time quick Q&A where you are certain no follow-up will be needed
• Temporary calls in CI/scripts to avoid polluting the session list
• Sensitive tasks where you do not want local records to be left behind

--ephemeral

claude -p --no-session-persistence

codex exec Parameters

Output and Results

--json

--output-schema FILE

-o, --output-last-message FILE

--color COLOR

always

never

auto

Execution Environment

-s, --sandbox MODE

read-only

workspace-write

danger-full-access

--full-auto

--sandbox workspace-write

--dangerously-bypass-approvals-and-sandbox

-C, --cd DIR

--skip-git-repo-check

--add-dir DIR

Model and Configuration

-m, --model MODEL

-p, --profile PROFILE

config.toml

-c, --config key=value

config.toml

--enable FEATURE

--disable FEATURE

--oss

--local-provider PROVIDER

lmstudio

ollama

Input

-i, --image FILE

PROMPT

-

-

codex exec resume Parameters

--json

-m, --model MODEL

--full-auto

workspace-write

--dangerously-bypass-approvals-and-sandbox

--skip-git-repo-check

--ephemeral

-i, --image FILE

-o, --output-last-message FILE

-c, --config key=value

config.toml

--enable FEATURE

--disable FEATURE

--last

--all

codex exec review Parameters

codex exec review [OPTIONS] [PROMPT]

--uncommitted

--base BRANCH

--commit SHA

--title TITLE

-m, --model MODEL

--json

--full-auto

workspace-write

--ephemeral

-o, --output-last-message FILE

Multi-turn Conversations

1. Run

   codex exec --json ...

   for the first time to get

   thread_id

2. Use

   codex exec resume --json "thread_id" "prompt"

   for follow-up questions

3. thread_id

   is tracked automatically, no need for users to manage it
4. Create new sessions for different tasks; multiple

   thread_id

   s do not interfere with each other

Model Selection

--model

gpt-5.4

gpt-5.4-mini

gpt-5.3-codex-spark

Recommended Parameter Combinations

gpt-5.4

workspace-write

--full-auto

gpt-5.4-mini

workspace-write

--full-auto

gpt-5.4-mini

read-only

--skip-git-repo-check

gpt-5.4

read-only

-C "$PWD" -o /tmp/result.txt

--json

gpt-5.4-mini

read-only

codex exec --json ... "Review ..."

gpt-5.4-mini

codex exec review --base main

gpt-5.4-mini

read-only

--skip-git-repo-check --ephemeral

gpt-5.4-mini

read-only

--output-schema schema.json -o result.json

Usage Rules

1. Always add

   --json

   for automated calls: Ensure output is parsable to extract

   thread_id

   and response content
2. Always explicitly pass

   --model

   : Avoid default model drift
3. Always run in the target project directory: Prefer

   cd /path/to/project

   or

   -C /path/to/project

4. Use

   workspace-write

   for coding tasks: Usually directly use

   --sandbox workspace-write

   or

   --full-auto

5. Use

   read-only

   or

   codex exec review

   for review tasks: Prevent accidental modifications
6. Maintain conversation continuity: Reuse

   thread_id

   for follow-ups on the same task; do not add

   --ephemeral

   if follow-up may be needed
7. Use

   --output-schema

   +

   -o

   for stable downstream parsing: Constrain the final result into a machine-consumable structure
8. Use stdin pipe for long prompts: Do not use positional parameters when prompts exceed ~500 characters or contain multi-line/special characters; write to a file first, then pass via

   - < file.txt

   to avoid getting stuck at

   Reading additional input from stdin...

9. Report results to users: After each call, extract the final response from JSONL and summarize it briefly for users
10. Distinguish between

    -o

    and

    --json

    responsibilities:

    -o

    is responsible for saving the last message to a file;

    --json

    is responsible for printing the entire event stream to stdout. Scripts often use both together.
11. Prefer

    read-only

    for non-coding native browser tasks: If you only want Codex to use Computer Use to open Chrome, browse web pages, and summarize content,

    --full-auto

    is not needed; add

    Do not modify local files.

    to the prompt as a double safeguard.

Prompt References

• Coding / Diagnosis / Planning / Narrow Fixes: Read references/task-prompt-recipes.md
• Code Review / Challenging Review / Test Gap Check: Read references/review-prompt-recipes.md
• Native Browser Research / Reddit or Community Sampling / Evidence-based Summary: Read references/browser-research-prompt-recipes.md

Examples

Coding Task

User: Use Codex to implement a TODO API in the current project

Step 1 - Create a new session:
cd /path/to/project && codex exec --json --full-auto --model gpt-5.4 "Implement a REST API for TODO items with CRUD endpoints. Use Express.js."

→ Parse output to get thread_id: "xxx", response: "Implemented server.js ..."

User: Add unit tests

Step 2 - Resume the session:
cd /path/to/project && codex exec resume --json --model gpt-5.4-mini "xxx" "Add unit tests for all the TODO API endpoints using vitest."

Resume the Most Recent Session

cd /path/to/project && codex exec resume --json --model gpt-5.4-mini --last "Continue the refactor and remove the dead helper functions."

thread_id

Code Review

# General read-only review
cd /path/to/project && codex exec --json --sandbox read-only --model gpt-5.4-mini "Review the changes in git diff HEAD~1. Focus on correctness, security, and missing tests."

# Built-in review: Compare with main
cd /path/to/project && codex exec review --json --model gpt-5.4-mini --base main

# Review uncommitted changes
cd /path/to/project && codex exec review --json --model gpt-5.4-mini --uncommitted

Structured Output and Write to File

cd /path/to/project && codex exec --json --sandbox read-only --model gpt-5.4-mini \
  --output-schema ./review-schema.json \
  -o /tmp/review-result.json \
  "Review src/todo.ts and output summary, risks, and suggested tests."

Native Browser Research (Only Final Answer Needed)

codex exec \
  -m gpt-5.4 \
  --sandbox read-only \
  --skip-git-repo-check \
  -C "$PWD" \
  -o /tmp/codex-last.txt \
  "Use Computer Use on my Mac. Open Google Chrome, go to Reddit, search for 'Duolingo review', open 3 representative posts (one positive, one negative, one long-term review), then summarize the findings in Chinese. Do not modify local files."

Native Browser Research (Both Event Stream and Final Answer Persistence)

codex exec \
  -m gpt-5.4 \
  --sandbox read-only \
  --skip-git-repo-check \
  -C "$PWD" \
  --json \
  -o /tmp/codex-last.txt \
  "Use Computer Use on my Mac. Open Google Chrome, search Reddit for Duolingo reviews, open a few representative posts, and then summarize them in Chinese. Do not modify local files."

/tmp/codex-last.txt

Image Input

cd /path/to/project && codex exec --json --sandbox read-only --model gpt-5.4-mini \
  -i ./screenshots/login-bug.png \
  "Describe the UI issue in this screenshot and propose a minimal fix plan."

Long Task Prompt (Recommended)

# 1. Write complex prompt to a file
cat > /tmp/task-prompt.txt <<'PROMPT_EOF'
Please complete the following tasks in the current repository:
1. First read the README and tests
2. Only modify files directly related to the issue
3. First add tests, then modify the implementation, and finally run verification
PROMPT_EOF

# 2. Read from stdin using - to avoid stuck long positional parameters
codex exec --json --sandbox workspace-write --full-auto --model gpt-5.4 \
  --skip-git-repo-check - < /tmp/task-prompt.txt > /tmp/task-out.jsonl 2>&1

Pass Long Prompt via stdin

cat ./prompt.md | codex exec --json --sandbox workspace-write --model gpt-5.4 -

- < file.txt