codex-task

A small portable tool that lets Claude Code, opencode, Cline, Cursor, or any CLI coding agent delegate a self-contained coding task to OpenAI's codex CLI and get back a structured JSON result — billed against the user's ChatGPT subscription, not the API.

Companion to codex-image-gen: same installer patterns, same target registry approach, different runtime payload.

Single mode: feed it a --prompt (or --prompt-file), it runs codex exec against your project, and emits JSON like:

{
  "ok": true,
  "taskResult": "completed",
  "summary": "Renamed getCwd to getCurrentWorkingDirectory across 8 files; updated 3 tests.",
  "details": "Searched the repo for all occurrences of `getCwd` (15 hits). Renamed the function and call sites, updated import names, and adjusted the 3 tests that asserted on the old name. One TODO comment in `src/legacy.js` references the old name; left as-is since it's purely informational.",
  "files": {
    "src/utils/paths.js": "edited",
    "src/server/routes.js": "edited",
    "tests/paths.test.js": "edited"
  },
  "workdir":     "/abs/path/to/project",
  "sessionDir":  null,
  "model":       "gpt-5.5",
  "permissions": "workspace-write",
  "reasoningEffort": null,
  "warnings":    [],
  "durationMs":  84210
}

Action values are created, deleted, or edited by default. Pass --track-references to include referenced files too. The parent agent (Claude Code etc.) can audit changes without reading codex's full transcript.

Default permissions are read-only — codex can read your project but cannot modify any files. Pair with --permissions workspace-write when you want codex to actually edit. read-only is the right default for the bulk of delegated work: investigations, audits, codebase questions, multi-file analysis.

Ships with an Anthropic-style SKILL.md that the installer registers with each detected coding-agent harness (Claude Code, opencode, Cline, Cursor, …) so the agent knows when and how to invoke it.

Why

When you're running on a Claude (or other paid) subscription and want to delegate a chunk of agent work — a multi-file refactor, scaffolding pass, exploratory investigation — to a fresh codex context, paying for that delegation in API tokens stings. codex exec against an authed ChatGPT plan bills the work to the user's existing subscription quota. This tool wraps codex exec with the right flags, environment, and prompt template so the delegating agent can call it without thinking about the gotchas — and gets back a stable JSON contract for what changed.

What's in this directory

Prerequisites

1. Node 22+ on PATH.
2. codex CLI on PATH, authed against a ChatGPT plan.
   • Install: see https://github.com/openai/codex for the current canonical install command on your platform.
   • Auth: codex login (uses ChatGPT account; opens a browser for OAuth).
3. A paid ChatGPT plan (Plus, Pro, or Team) if you want to avoid burning API tokens. The free tier may not include codex exec quota; check current ChatGPT terms.
4. A coding-agent harness that reads SKILL.md (only needed if you want the skill auto-invoked from inside an agent). The installer detects and registers with whichever of these are present:
   • Claude Code — skill at ~/.claude/skills/codex-task/SKILL.md, with a matching Bash(...) allow rule auto-patched into ~/.claude/settings.json.
   • opencode — skill at ~/.config/opencode/skills/codex-task/SKILL.md. opencode permits external commands by default, so no settings patch is needed.
   • Cline — skill at ~/.cline/skills/codex-task/SKILL.md (Cline's user-global Skills system). No settings patch is needed.
   • Cursor — skill at ~/.cursor/skills/codex-task/SKILL.md (Cursor's Skills system). No settings patch is needed. (Cursor also reads ~/.claude/skills/ and ~/.codex/skills/ as compatibility paths.)
   • The installer always installs the skill for Claude Code (it's the historical default — most users running this installer have Claude Code) and adds opencode / Cline / Cursor opportunistically when their config dirs exist. Use --target= / --all / --no-<id> to override (see below).
   • Explicit-only target — the installer also knows about ~/.agents/skills/, a cross-harness shared dir read by Cursor and opencode. It is never auto-installed (would duplicate the per-harness installs into harnesses that read both paths). Pass --target=agents to use it intentionally, typically alongside --no-cursor --no-opencode to dedupe.

codex routes to subscription billing only when OPENAI_API_KEY is not set in the environment. The wrapper deletes that variable before spawning codex, so the user's shell can have the API key set for other purposes without breaking subscription routing for this tool.

Install

git clone https://github.com/NicholasMTElliott/codex-task.git
cd codex-task
node install.mjs

The runtime bin also forwards installer flags, so a copy of codex-task.mjs that has install.mjs next to it (repo checkout, npm package dir, or a ~/.codex-task/ written by a current installer) can run the installer. If install.mjs is missing (e.g. a ~/.codex-task/ from an older installer), the runtime prints a plain error to stderr and exits 1:

codex-task --install            # same as node install.mjs
codex-task --list-targets
codex-task --uninstall

Target-selection flags (--target=, --all, --no-<id>) forward too, e.g. codex-task --install --target=claude,cursor.

If you invoke the runtime for a task and the skill is not registered with any known harness, it prints a one-line warning to stderr and adds the same message to the result's warnings array — the run itself proceeds normally. Silence it with --no-install-check or CODEX_TASK_SKIP_INSTALL_CHECK=1.

What the installer does

1. Verifies node and codex are on PATH.
2. Copies codex-task.mjs, install.mjs, SKILL.md, and README.md to ~/.codex-task/ (shared across all harnesses; the installer and template are included so node ~/.codex-task/codex-task.mjs --install / --uninstall keep working from the installed copy).
3. Renders SKILL.md with the absolute install path baked in.
4. For each selected target harness, drops the rendered SKILL.md into the harness's user-global skills dir:
   • ~/.claude/skills/codex-task/SKILL.md (Claude Code)
   • ~/.config/opencode/skills/codex-task/SKILL.md (opencode)
   • ~/.cline/skills/codex-task/SKILL.md (Cline)
   • ~/.cursor/skills/codex-task/SKILL.md (Cursor)
   • ~/.agents/skills/codex-task/SKILL.md (cross-harness — explicit-only)
5. For Claude Code, also auto-patches the permissions.allow array in ~/.claude/settings.json with the Bash(...) rule that pre-approves the tool. Idempotent — safe to re-run; falls back to printing the rule if settings.json is malformed. opencode, Cline, and Cursor are permissive by default and get no settings patch.

Installer flags

All flags work identically through the runtime bin: codex-task --install --no-opencode, codex-task --list-targets, etc.

To remove:

node install.mjs --uninstall     # or: codex-task --uninstall

Manual invocation

POSIX (bash/zsh) — read-only investigation (default permissions):

node ~/.codex-task/codex-task.mjs \
  --prompt "Find every place in this repo that imports lodash.merge and list options for replacing each one."

Refactor (writes files — opt in with --permissions):

node ~/.codex-task/codex-task.mjs \
  --permissions workspace-write \
  --prompt "Rename getCwd to getCurrentWorkingDirectory across the repo, including tests."

With a long brief from a file, a specific model, explicit reasoning effort, and persistent output:

node ~/.codex-task/codex-task.mjs \
  --prompt-file ./refactor-brief.md \
  --permissions workspace-write \
  --model gpt-5.6-terra \
  --reasoning-effort high \
  --cwd path/to/project \
  --out /tmp/refactor-result.json

Windows PowerShell — ~ does not expand in arguments, use $env:USERPROFILE:

node "$env:USERPROFILE\.codex-task\codex-task.mjs" `
  --prompt "Find every place in this repo that imports lodash.merge and list options for replacing each one."

Output is JSON on stdout. Codex's own progress chatter is captured silently by default; pass --stream-thinking to mirror it live to stderr. The per-session scratch dir lives under your OS temp directory (not inside the project), is removed automatically on success, and is preserved on failure — sessionDir in the JSON output points at it.

Parameters

Task input (one required)

• --prompt — inline task description. Anything you'd tell codex to do.
• --prompt-file — path to a UTF-8 text file containing the task description. Mutually exclusive with --prompt. Trailing whitespace trimmed; internal newlines preserved.

Workspace

• --cwd (optional). Working directory codex operates inside (relative to caller cwd, or absolute). Default: caller cwd. Codex's sandbox is bounded by this directory (modulo --permissions danger-full-access).

Codex pass-throughs

• --model (optional, default gpt-5.5). Model codex should use. The set of supported values is plan-dependent — codex validates server-side and returns an error for anything your plan doesn't include. Common known names: gpt-5.5, gpt-5.5-codex, gpt-5, gpt-5-codex, and the GPT-5.6 tiers gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna.

  • GPT-5.6 tier guidance (2026-07-09, CLI-validated with codex-cli 0.144.1: all three names accepted --model and completed a trivial prompt):
    • gpt-5.6-sol — flagship. Additionally accepts --reasoning-effort max and ultra (CLI-validated: both exit 0).
    • gpt-5.6-terra — balanced default among the 5.6 tier. Effort enum CLI-validated via a server 400: none|minimal|low|medium|high|xhigh.
    • gpt-5.6-luna — cheap/fast.
  • Effort sets are model- and plan-dependent (not just a fixed list), which is why the wrapper never validates --reasoning-effort client-side — codex is the source of truth.

• --reasoning-effort (optional, unset by default). Reasoning effort level, passed through to codex as -c model_reasoning_effort="<level>". Plan- and model-dependent; codex validates server-side, so the wrapper performs no client-side enumeration. Commonly-seen levels (hints only, not a validated enum): minimal|low|medium|high|xhigh, plus max/ultra on some tiers (e.g. gpt-5.6-sol).

• --permissions (optional, default read-only). Sandbox policy for codex. Maps to codex's --sandbox:

  • read-only (default) — codex can read but not modify any file in the workspace.
  • workspace-write — codex can read AND write inside --cwd. Files outside the workdir remain read-only.
  • danger-full-access — codex can read AND write anywhere on the filesystem.

  The structured result is captured via codex's --output-last-message flag (a codex-process write, not a model write), so it works under any sandbox mode including read-only.

• --profile (optional). Codex config profile name. If set, codex loads option defaults from this profile in ~/.codex/config.toml.

There is no wrapper --search flag. If the delegated task needs current web information, say so in the prompt, e.g. --prompt "Search the web for the latest Codex release, then update docs/version.md." Codex can perform web search from codex exec when explicitly instructed.

Wrapper options

• --out (optional). Also write the result JSON to this file path (still printed to stdout).
• --debug (optional flag). Keep the per-session scratch dir on success. Default cleans it up. Failed runs always preserve scratch regardless.
• --stream-thinking (optional flag). Mirror Codex live stdout/stderr to wrapper stderr. Default is silent capture only.
• --track-references (optional flag). Include referenced entries in files. Default omits referenced-only files.
• --quiet (optional flag). Compatibility flag; live thinking is already off by default, and --quiet suppresses streaming even when combined with --stream-thinking.
• --no-install-check (optional flag). Skip the startup check that warns when the codex-task skill is not registered with any known harness. The warning goes to stderr and into the result's warnings array; it never blocks the run. CODEX_TASK_SKIP_INSTALL_CHECK=1 in the environment has the same effect.
• --retries N (optional, default 0). Retry non-zero codex exec exits whose final diagnostic lines classify as transient infrastructure: model capacity / 429 / rate-limit / temporarily-unavailable / overloaded errors, or sandbox-wrapper preparation failures. Durable failures are excluded first: auth, unsupported model/effort, durable quota or usage-cap limits, generic "please try again" text, JSON/contract failures, and every clean exit-0 result regardless of taskResult.

Output JSON shape

{
  "ok": true,
  "taskResult": "completed",
  "summary":     "<one or two sentences>",
  "details":     "<markdown>",
  "files":       { "<path>": "created|deleted|edited", ... },
  "workdir":     "<absolute --cwd>",
  "sessionDir":  null,
  "model":       "<model used>",
  "permissions": "<permissions mode used>",
  "reasoningEffort": null,
  "warnings":    [],
  "durationMs":  12345
}

When --reasoning-effort high is passed, reasoningEffort echoes the resolved level instead of null:

  "model":       "gpt-5.6-terra",
  "permissions": "workspace-write",
  "reasoningEffort": "high",

ok is true only when codex exits cleanly, its final message parses, and taskResult is completed. On false, inspect taskResult, error, details, and warnings; sessionDir is preserved for wrapper/runtime failures.

taskResult values:

• completed — requested outcome was fully achieved.
• partial — some requested outcomes were achieved, but not all.
• blocked — sandbox, auth, dependency, or another external constraint prevented the requested outcome.
• failed — Codex could not complete the requested outcome for another reason.

files action values are one of:

• created — file did not exist before; codex created it.
• deleted — file existed before; codex removed it.
• edited — file existed before; codex modified its contents.
• referenced — codex read the file as context but did not change it. Only present when --track-references is passed.

If codex returns an unknown action verb ("modified", "updated", etc.), the wrapper coerces it to "referenced" and emits a warning rather than failing the run. Referenced entries are omitted unless --track-references is set.

Inspect warnings for non-fatal anomalies: unknown action verbs, missing schema fields, cleanup failures.

reasoningEffort is the resolved --reasoning-effort level for this run, or null if the flag was omitted.

attempts is present only when --retries is greater than zero. It counts codex exec invocations, including the final successful or exhausted attempt. Each retried transient failure also adds a warning.

Using it from a coding-agent harness

Once installed, restart your agent if it was already running — most harnesses load skills and settings only at startup. After that, just ask for a delegatable task in any project; the parent agent reads the skill description, decides it matches your request, and runs the tool for you.

Example dialogue (Claude Code):

You: I want to rename getCwd to getCurrentWorkingDirectory everywhere it appears in this repo, including tests. Use codex-task — I'd rather not burn this conversation on it.

Claude: (invokes node ~/.codex-task/codex-task.mjs --permissions workspace-write --prompt "Rename getCwd to getCurrentWorkingDirectory across this repo. Update every call site, every import, every test. Do not change anything else.", waits ~60s, then reads the JSON and validates ok, taskResult, summary, and files)

The same rendered SKILL.md is dropped into every target harness's skills dir, so the experience is identical from Claude Code, opencode, Cline, Cursor, or any other harness that reads Anthropic-style skill frontmatter (name + description). Harnesses that don't recognize the allowed-tools field simply ignore it.

Other coding-agent harnesses (not auto-registered)

For harnesses without a user-global Skills system, register the tool manually per project — paste a short "Delegation tool available at: ~/.codex-task/codex-task.mjs" block into your project-root AGENTS.md. The installer does not modify AGENTS.md automatically because it's typically checked in alongside the project and editing it without consent would be invasive.

If your harness has a stable user-global skills directory and you'd like first-class support, please open an issue — adding a target is a single entry in the TARGETS registry in install.mjs.

Updating

cd codex-task
git pull
node install.mjs

The installer is idempotent: re-running overwrites the installed copy in ~/.codex-task/, re-renders the skill into every selected target's skills dir, and detects existing allow rules without duplicating them.

Troubleshooting

1. Manual smoke test — isolates Node/codex issues from harness issues: