Skip to content
Skills Library
AI & agents · Automation

codex-agent

/codex-agent

Run the OpenAI Codex CLI non-interactively as a child agent and get back its final reply plus a session id, with the prompt supplied as arguments, a file, or stdin, and session resume support. Use to delegate a self-contained brief to a Codex agent, to get a second-vendor opinion alongside a Claude agent, or to continue an earlier non-interactive Codex run.

Licence
MIT
Last repository change
15.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/codex-agent.mjs

What it does and when to use it

Run the OpenAI Codex CLI non-interactively as a child agent and get back its final reply plus a session id, with the prompt supplied as arguments, a file, or stdin, and session resume support. Use to delegate a self-contained brief to a Codex agent, to get a second-vendor opinion alongside a Claude agent, or to continue an earlier non-interactive Codex run.

Original author description

Run the OpenAI Codex CLI non-interactively as a child agent and get back its final reply plus a session id, with the prompt supplied as arguments, a file, or stdin, and session resume support. Use to delegate a self-contained brief to a Codex agent, to get a second-vendor opinion alongside a Claude agent, or to continue an earlier non-interactive Codex run.

How it works

  1. Execution
  2. Prerequisites
  3. Usage
  4. Environment Variables
  5. Output
  6. Troubleshooting
  7. Notes
Original SKILL.md headings · 152 lines, 752 words
SKILL.md preview
---
name: codex-agent
description: Run the OpenAI Codex CLI non-interactively as a child agent and get back its final reply plus a session id, with the prompt supplied as arguments, a file, or stdin, and session resume support. Use to delegate a self-contained brief to a Codex agent, to get a second-vendor opinion alongside a Claude agent, or to continue an earlier non-interactive Codex run.
license: MIT
allowed-tools: Bash
---

# Codex Agent (wrapper)

> **This runs an autonomous agent with approvals and sandboxing disabled.**
> The wrapper invokes `codex exec --dangerously-bypass-approvals-and-sandbox`,
> because a non-interactive run has no one to approve anything. The child agent
> can read, write and execute in whatever directory you launch it from. Only
> give it briefs you would be willing to run yourself.

## Execution

Works in both foreground and background:

```
# Foreground (blocks until done - use a long timeout, runs can take minutes)
Bash(command: "node \"~/.claude/skills/codex-agent/scripts/codex-agent.mjs\" Your prompt here", timeout: 600000)

# Background (non-blocking - you are notified when it finishes)
Bash(command: "node \"~/.claude/skills/codex-agent/scripts/codex-agent.mjs\" Your prompt here", run_in_background: true)
```

Background is preferred when launching multiple agents in parallel. Codex
routinely takes 2-3x longer than Claude on the same brief.

---

Thin wrapper around the `codex` CLI for non-interactive use:

- Provide the prompt via arguments, `PROMPT_FILE`, or stdin (briefs are byte-exact)
- Model selection via `--model` or `CODEX_MODEL`
- Session resume via `--resume` or `CODEX_SESSION`
- Auto-detects OAuth login (`~/.codex/auth.json`) or API keys
- Clear diagnostics on failure

## Prerequisites

- **Node 18 or newer** (`node --version`)
- **Codex CLI v0.80.0+**: `npm install -g @openai/codex@latest`
- **Authentication**, one of:
  1. `codex login` for ChatGPT OAuth (creates `~/.codex/auth.json`)
  2. `OPENAI_API_KEY` environment variable
  3. `CODEX_API_KEY` environment variable (exec mode only)

Nothing else. The wrapper is a single Node script with no dependencies, so it
does not need bash, GNU `grep -P`, GNU `sort -V`, awk or sed. It runs the same
on Linux, macOS, WSL, and Windows (PowerShell, cmd, or Git Bash).

`CODEX_HOME` is honored if you have relocated your Codex configuration.

## Usage

```bash
# Arguments
node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" Your prompt here

# File via env var (preferred for big briefs - byte-exact off stdin)
PROMPT_FILE=task.md node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs"

# Stdin
cat task.md | node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs"
```

On Windows PowerShell the `VAR=value command` prefix form is not valid syntax.
Use `$env:PROMPT_FILE="task.md"` on its own line first, then run the command.

### Session Resume

```bash
# Resume most recent session
node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" --resume latest "Follow-up question"

# Resume by UUID
node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" --resume 019bf3a2-40ce-7923-b501-3d4ebd00aed3 "Continue"

# Via environment variable
CODEX_SESSION=latest node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" "Follow-up"
```

### Model Selection

```bash
# Via flag
node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" --model gpt-5.2-codex "Your prompt"

# Via environment variable
CODEX_MODEL=gpt-5.2-codex node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" "Your prompt"
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PROMPT_FILE` | Read prompt from this file (byte-exact off stdin) |
| `CODEX_MODEL` | Model to use (passed as `--model`) |
| `CODEX_SESSION` | Session to resume (`latest` or UUID) |
| `CODEX_HOME` | Codex config/auth directory (default `~/.codex`) |
| `OPENAI_API_KEY` | API key authentication |
| `CODEX_API_KEY` | API key for exec mode |
| `AGENT_LOG_DIR` | Where run logs go (default: system temp `/agentic-coding-tools`) |

## Output

Returns the plain text response followed by the session ID:

```
<response text>

[session_id: <uuid>]
```

Capture the session ID to continue the conversation with `--resume <uuid>`.

Every run also saves its output to a log file whose path is printed to stderr
as `[output_file: ...]`. **Read the path the wrapper printed** — do not guess
it or glob for the newest file, because parallel runs share the directory.

If a background run's output was not captured, read the `[output_file:]` path
instead.

## Troubleshooting

Diagnostics are shown automatically on any failure. You can also run:

```bash
node "~/.claude/skills/codex-agent/scripts/codex-agent.mjs" --version
```

Common issues:

1. **No auth configured**: run `codex login`, or set `OPENAI_API_KEY`
2. **codex not found**: install with `npm install -g @openai/codex`
3. **Session not found**: check `~/.codex/sessions/` for valid UUIDs
4. **Connection errors**: check network connectivity and auth token expiry
5. **`no prompt: stdin was empty`**: the wrapper refuses to run on an empty
   prompt. This usually means it was launched from a parent that closed stdin.
   Pass the prompt as arguments or via `PROMPT_FILE`.

## Notes

- Runs `codex exec --dangerously-bypass-approvals-and-sandbox` (see the warning
  at the top), with `--skip-git-repo-check` so it works outside a git repo.
- The prompt is always delivered on stdin (`codex exec ... -`), including
  resume follow-ups. A large brief is therefore never truncated at the ~128KB
  argument-length cap, and no user text passes through platform command-line
  quoting.
- stdout and stderr are captured separately. Recent codex builds put the final
  agent message on stdout and the header, transcript replay and "tokens used"
  footer on stderr; merging them made the reply and the footer interleave
  nondeterministically.
- Sessions are stored in `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`.
- For bidirectional streaming, use `codex app-server` directly (JSON-RPC).
Files in this package (2)
  • SKILL.md 6 KB
  • scripts/codex-agent.mjs 12 KB

Versions

RepositoryScoreLicence
This page · thesylvester/agentic-coding-tools100MIT
majiayu000/spellbook100MIT

Database snapshot: 13.11.2026 · package version 71ff3a67a3f9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100claude-agent
    Run the Claude Code CLI non-interactively as a child agent and get back its final reply plus a session id, with the prompt supplied as arguments, a file, or stdin, true session resume, and an opt-in liveness monitor. Use to delegate a self-contained brief to a full Claude agent,…
  • 100codex
    Run OpenAI Codex CLI (via AWS Bedrock) non-interactively to get a second opinion, review a diff, or delegate a task. Use when the user asks to "run codex", "ask codex", or get a Codex review/answer.
  • 95codex-exec
    Run OpenAI Codex CLI non-interactively to execute tasks, generate code, or get a second opinion. Use this skill whenever the user says "run codex", "ask codex", "codex exec", "have codex do", "send to codex", "pipe to codex", or wants to delegate a task to Codex for a second…
  • 100code-mate-codex
    Run Codex CLI non-interactively for coding tasks. Use when the user asks to delegate work to Codex.
  • 100codex
    Route a task to OpenAI's Codex CLI (`codex exec`) instead of doing it yourself. Use this skill ANY time the user names codex or types `/codex` — even for routine work Claude could handle, because the user is choosing to delegate. The intent: 'ask codex', 'have codex…
  • 100codex
    Use when you need to run OpenAI Codex CLI from another agent (Claude Code or any shell-capable agent): hand it a task with `codex exec`, run several Codex workers in parallel, continue a Codex session with `codex exec resume`, run `codex exec review`, capture its final report,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.