Skip to content
Back to search

use-codex

SkillWorks with Claude CodeGitHub

Delegate a planned development or infra job to a Codex agent (gpt-6.2 sol/astra) running in a confined Docker container, so Claude spends its usage on planning and review instead of bash/edit tool calls. Claude writes one crisp TODO, a runner executes Codex against it and kills or steers it the moment it runs an unlisted command or touches an unlisted file. Use when the user says "use codex", "delegate to codex", "/use-codex", "save claude usage", or hands over a multi-step build/refactor/test-writing job. Only worth it for big generation jobs (roughly 15 KB / 400+ lines of new code or many files): measured on small and medium jobs it costs Claude MORE tokens and 3-5x more time, so do those directly.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/branson404--use-codex/badge.svg)](/listings/branson404--use-codex)

HTML

<a href="/listings/branson404--use-codex"><img src="/api/listings/branson404--use-codex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/branson404/use-codex ~/.claude/skills/use-codex

Restart Claude Code. Then say "use codex to ..." or run `/use-codex`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 81 lines
  1. ---
  2. name: use-codex
  3. description: Delegate a planned development or infra job to a Codex agent (gpt-6.2 sol/astra) running in a confined Docker container, so Claude spends its usage on planning and review instead of bash/edit tool calls. Claude writes one crisp TODO, a runner executes Codex against it and kills or steers it the moment it runs an unlisted command or touches an unlisted file. Use when the user says "use codex", "delegate to codex", "/use-codex", "save claude usage", or hands over a multi-step build/refactor/test-writing job. Only worth it for big generation jobs (roughly 15 KB / 400+ lines of new code or many files): measured on small and medium jobs it costs Claude MORE tokens and 3-5x more time, so do those directly.
  4. ---
  5. # use-codex
  6. Claude plans and reviews. Codex does the typing. A runner enforces the plan.
  7. ## 0. Gate (10 seconds)
  8. - Small/medium job (under roughly 15 KB / 400 lines of new code)? Do it yourself. Measured (Sonnet 5.5 high): delegating cost Claude +10% tokens on small, +4% on large, break-even at ~17 KB, and 3-5x the wall time. It pays off only above that, or when you want to move work onto Codex's quota.
  9. - `python3 ~/.claude/skills/use-codex/scripts/codex_run.py check TODO PROJECT` prints `login: present|MISSING`.
  10. If Codex answers `refresh token was revoked`, stop and tell the user to run `! codex login` (interactive; you cannot).
  11. - Only hard requirements: Codex CLI installed + logged in, macOS or Linux. `backend: auto` uses Docker when it works on Linux, else the
  12. `local` backend (Codex's own sandbox on a scratch copy). Docker image default `python:3.12-slim` has no git/node; set `image:` if needed.
  13. ## 1. Write the TODO (this is where usage is saved or wasted)
  14. Copy `templates/TODO.template.md`. Rules:
  15. - You have already read the code; the TODO says WHAT changes, not how to explore. Exact paths, signatures, behaviours.
  16. - One step = one file or one behaviour, each with a `Done when:` check. Aim for under ~60 lines total.
  17. - `write:` is the whole write scope. Dirs end with `/`. Never `.`. Codex cannot touch anything else (read-only mount).
  18. - `run:` lists the only non-read-only commands it may use (tests, linters, builds). Anything else = violation.
  19. - Forbid git commits, installs, network. Claude commits after review.
  20. - Put acceptance commands in `## Acceptance`; you re-run them yourself afterwards.
  21. - Order the checks sensibly: never require a green test run at a step that only a later step makes green (a real run blocked on exactly that).
  22. - Leave `backend:` unset. `auto` picks Docker where it works; set `local` only on macOS. Docker's default image has no project dependencies: build or name an image that has them via `image:`.
  23. - Do not paste large code or write essays. Short, literal, checkable.
  24. Model/effort: `sol` + `high` default. `astra` only for hard architecture or gnarly debugging. `effort: low` for mechanical edits,
  25. `medium` for straightforward features. `xhigh` or above only with a reason you can state in one sentence. Aliases resolve to the
  26. newest listed model in `~/.codex/models_cache.json`.
  27. ## 2. Dry check
  28. `python3 ~/.claude/skills/use-codex/scripts/codex_run.py check TODO PROJECT` shows model, scopes, masked secret files (.env, keys), limits.
  29. ## 3. Run (background) and watch
  30. ```
  31. python3 ~/.claude/skills/use-codex/scripts/codex_run.py start TODO PROJECT # run_in_background: true
  32. ```
  33. The runner confines Codex and checks every event live. `docker`: container (`--cap-drop ALL`, project read-only, only `write:` paths
  34. writable, `.env`/keys blanked, login copy deleted afterwards). `local`: Codex's native sandbox on a scratch copy; only `write:` paths
  35. are copied back, any other change is reverted and reported as a violation. It prints one compact line per action and writes
  36. `~/.cache/use-codex/<run>/summary.log`. You do not poll. Optionally attach a Monitor to
  37. `tail -F <run>/summary.log | grep --line-buffered -E 'VIOLATION|STALL|TIMEOUT|BUDGET|WARN|BLOCKED|RESULT'`.
  38. Auto-stopped (container killed) on: command not in the allowlist or touching paths outside `/work`, edit outside `write:`,
  39. unlisted tool use (MCP/web), more than `max-commands`, over `max-minutes`, no events for `stall-seconds`.
  40. ## 4. Streamline (steer) on a stop
  41. Exit codes: 0 done, 3 violation, 4 timeout/stall, 5 failed/blocked. Read only the last ~8 lines of `summary.log` and `result.json`.
  42. - Harmless drift (e.g. it tried `pip install` or wandered): `codex_run.py resume <run> "one-line correction"`. Same session, same limits.
  43. - Needs something not in the TODO: add it to the TODO (new `write:`/`run:` entry) and start a fresh run, or do that bit yourself.
  44. - Same violation twice, or anything that looks adversarial (reading `/codexhome`, curl, git push): `stop`, take over or rewrite the TODO.
  45. - `BLOCKED:` means the step was wrong or underspecified. Fix the TODO; do not argue with it.
  46. Max two resumes per job. After that, take over.
  47. ## 5. Verify (never trust the report alone)
  48. - `git -C PROJECT diff --stat` (or `ls`) to confirm only expected files changed.
  49. - Run the `## Acceptance` commands yourself. Read `last_message.md` (not the event stream).
  50. - Then commit/PR as the user wants. Codex never commits.
  51. ## 6. Cleanup
  52. Automatic at the end of every run (container removed, login copy deleted, empty placeholders removed). If the runner itself was
  53. killed: `codex_run.py cleanup <run>`. Runs live under `~/.cache/use-codex/`; delete old ones freely.
  54. ## Keeping usage under control
  55. - Short TODO, narrow `write:`, `effort` no higher than needed, `max-minutes`/`max-commands` set per job.
  56. - One worker per job. Parallel workers only with disjoint `write:` sets and independent TODOs.
  57. - Do not re-explain context to Codex that it can read in the files; do not re-read what Codex already summarised.
  58. - Check `tokens=` on the RESULT line; if a job type is costly, lower effort or tighten the TODO next time.
  59. ## Known limits (be honest about them)
  60. - `local` is weaker than `docker` (it relies on Codex's own sandbox + the scratch copy) and a real macOS run has not been verified; on a Linux host that blocks user namespaces Codex's native sandbox cannot start, so use `docker` there.
  61. - `docker`: network stays on (Codex needs its API). The monitor, not the network, blocks `curl`; an allowlisted command can still call out. Codex's login sits in `/codexhome` in the container; reading it is blocked by the monitor, not the filesystem.
  62. - The policy parses shell text. It blocks `$(...)`, backticks and nested shells by design; unusual-but-legit commands may need a `run:` entry.
  63. - Codex rotates refresh tokens. The runner copies a refreshed login back to `~/.codex/auth.json` after each run; never copy auth files by hand.
  64. - `codex_run.py selftest` re-validates the policy engine offline. `--probe` on `start` verifies the container confinement without a model call.
  65. - Verified live (2026-11-21, codex-cli 0.170, gpt-6.2-sol): a real job ran end to end, `BLOCKED` -> `resume` -> `DONE` worked, files stayed inside `write:`, `.env` untouched, container and login copy removed. The monitor was also replayed on the real `events.jsonl` with stricter policies and flagged the right command/edit. Codex usually obeys the allowlist in its own prompt and prints `BLOCKED`, so the kill path is a backstop, not the common case.
  66. - Codex needs its sibling binaries (`codex-code-mode-host`, `codex-exec-server`) next to `codex`; the runner mounts all `codex*` files. If a run says the tool host is missing, that is why.
  67. - Underspecified TODOs cost a resume: e.g. `unittest discover -t .` needs `tests/__init__.py`, which must be in `write:`/Steps. Name every file a step implies.
  68. - The runner prints `WARN` if it sees command events it cannot parse (format drift); then read `events.jsonl` before trusting the run.
README.md · README · 132 lines
  1. # use-codex
  2. A [Claude Code](https://claude.com/claude-code) skill that hands planned development work to an
  3. [OpenAI Codex](https://github.com/openai/codex) agent, so Claude spends its usage on planning and review
  4. instead of its own bash and edit calls.
  5. Claude writes one short TODO. `codex_run.py` runs `codex exec --json` for that TODO in a confined environment
  6. (a locked-down Docker container, or Codex's native sandbox on a scratch copy) and checks every command and file edit Codex makes against the TODO's allowlist. If Codex steps outside
  7. the plan, the container is killed, and Claude can steer the same session with `resume`. Claude then verifies the
  8. result itself.
  9. ```
  10. Claude: plan -> TODO.md ──> codex_run.py start ──> confined run (docker | local)
  11. │ └─ codex exec --json (gpt-6.2 sol / astra)
  12. └─ live monitor: unlisted command / edit / tool? kill
  13. Claude: read summary, re-run acceptance checks, commit
  14. ```
  15. ## Requirements
  16. - **macOS or Linux** (Windows: use WSL2; native Windows is not supported)
  17. - **[Codex CLI](https://github.com/openai/codex) installed and logged in** (`codex login`). That is all the default setup needs.
  18. - Python 3.9+ (standard library only)
  19. - Optional: Docker on Linux. If it is available the runner uses it for stronger isolation (see backends below).
  20. ## Install
  21. ```bash
  22. git clone https://github.com/branson404/use-codex ~/.claude/skills/use-codex
  23. ```
  24. Restart Claude Code. Then say "use codex to ..." or run `/use-codex`.
  25. ## Use
  26. 1. Copy `templates/TODO.template.md` and fill it in. The header is machine-read:
  27. ```
  28. model: sol # sol (default) | astra | any exact model id
  29. effort: high # low | medium | high | xhigh
  30. write: src/foo/, tests/test_foo.py # the ONLY writable paths (dirs end with /)
  31. run: pytest -q # extra commands Codex may run (prefix match, no commas inside one)
  32. max-minutes: 20
  33. max-commands: 60
  34. ```
  35. 2. Check, then run (put `start` in the background):
  36. ```bash
  37. python3 scripts/codex_run.py check TODO.md /path/to/project
  38. python3 scripts/codex_run.py start TODO.md /path/to/project
  39. ```
  40. 3. Watch `~/.cache/use-codex/<run>/summary.log` (one compact line per action). Exit codes: `0` done,
  41. `3` violation, `4` timeout/stall, `5` failed or `BLOCKED`.
  42. 4. Steer or stop: `resume <run> "one-line correction"`, `stop <run>`, `status <run>`, `cleanup <run>`.
  43. `model: sol` / `astra` resolve to the newest listed `gpt-X-sol` / `gpt-X-astra` in `~/.codex/models_cache.json`.
  44. ## Does it save Claude usage?
  45. Honest answer: **only on large jobs.** Measured on 2026-11-22 with Claude Sonnet 5.5 (high effort) doing the same four
  46. tasks directly vs through this skill (one run per cell, tokens = a subagent's total, which includes about 49k of fixed
  47. baseline, so the differences are small but real):
  48. | Task (new code written) | Claude directly | Claude via use-codex | Difference | Codex input (cached) / output tokens |
  49. |---|---|---|---|---|
  50. | S, 0.7 KB | 49,212 | 54,474 | **+10.7%** | 84,084 (76,928) / 765 |
  51. | M, 3.6 KB | 51,043 | 55,885 | **+9.5%** | 87,826 (82,560) / 1,657 |
  52. | L, 8.5 KB | 53,950 | 56,304 | **+4.4%** | 217,895 (198,272) / 5,666 |
  53. | XL, 17 KB | 58,407 | 57,840 | **-1.0%** | 218,689 (200,064) / 7,096 |
  54. - Claude's tool calls went from 2-3 to 6-7 per job, and wall time from 9-54 s to 47-194 s.
  55. - What Claude has to *write* is what shrinks: the TODO stays about 1-4 KB while the code it replaces grows to 17 KB.
  56. That is where the saving comes from, and why break-even is near 17 KB. Extrapolated from these four points (not
  57. measured), a 50 KB job would save roughly 15%.
  58. - Quality was equal: every run passed its unit tests and an independent hidden check.
  59. - **Codex side:** each job used 82k-219k input tokens (about 91% cached) and 0.5k-7k output tokens, and moved the
  60. Codex quota meters by 0-1 points of the 5-hour window and 0-1 of the weekly window. A fixed ~76k cached prompt
  61. overhead per run means many tiny jobs are wasteful; batch work into fewer, larger TODOs.
  62. - Limits of this test: one run per cell, one model, tokens rather than dollars, Linux Docker backend only.
  63. ## Backends
  64. `backend: auto` (the default) picks one per run. Override with `backend: docker` or `backend: local` in the TODO header.
  65. | | `docker` (auto on Linux with a working Docker) | `local` (auto on macOS, or Linux without Docker) |
  66. |---|---|---|
  67. | Where Codex runs | locked-down container (`--cap-drop ALL`, non-root, resource limits) | on your machine, inside Codex's own sandbox (`workspace-write`: Seatbelt on macOS, bwrap on Linux), never `danger-full-access` |
  68. | Project | mounted **read-only**; only `write:` paths are writable | **scratch copy** (no `.git`, dependency dirs or secret files); after the run only `write:` paths are copied back |
  69. | Out-of-scope edits | impossible (read-only mount) | detected by diff, **reverted** and reported as a violation |
  70. | Secrets | `.env`, `*.pem`, `*.key`, `.npmrc`, ... blanked | not copied into the scratch copy |
  71. | Login | your `~/.codex/auth.json` is copied to a short-lived run folder, deleted afterwards (a refreshed token is copied back; Codex rotates refresh tokens) | uses your normal Codex login in place, nothing copied |
  72. Both backends share the same live monitor:
  73. | Rule | Effect |
  74. |---|---|
  75. | Commands | read-only inspection plus the TODO's `run:` entries; `$(...)`, backticks, unlisted binaries and paths outside the project are violations |
  76. | Tools | MCP and web search are violations unless `web: yes` |
  77. | Budget | `max-commands`, `max-minutes`, and a stall timer (no events for 300 s) |
  78. ## Limits (please read)
  79. - **The monitor is not a security boundary against a hostile model.** The container (docker) or Codex's native sandbox
  80. (local) is. The monitor parses shell text and is a policy and cost guard; unusual but legitimate commands may need a
  81. `run:` entry.
  82. - The `local` backend is weaker than `docker`: it relies on Codex's own sandbox plus the scratch copy. Use `docker`
  83. on Linux when you can.
  84. - `docker`: network stays on (Codex needs its API); the monitor blocks `curl` and friends, but an allowlisted command
  85. can still make network calls. The run folder holds a short-lived copy of your login that the container user can
  86. read; the monitor blocks reads of it, the filesystem does not.
  87. - **Tested:** `docker` backend live on Linux/arm64 with codex-cli 0.170 and `gpt-6.2-sol`. The `local` backend's
  88. logic (scratch copy, diff, apply/revert, secret exclusion) is tested offline with a stand-in `codex` in CI on
  89. Linux and macOS; a real Codex job through `local` on macOS has **not** been verified yet. On Linux hosts that block
  90. user namespaces Codex's native sandbox cannot start, so use `docker` there.
  91. - Event parsing follows Codex's `--json` output; if it changes, the runner prints `WARN` instead of silently not
  92. policing.
  93. - Using Codex costs Codex usage. Keep TODOs short and `effort` low; a tiny job still used tens of thousands of
  94. (mostly cached) input tokens.
  95. - Check the Codex CLI's current terms before running automation against your account.
  96. ## Development
  97. ```bash
  98. python3 scripts/codex_run.py selftest # offline: policy engine, monitor, local backend (runs in CI on Linux + macOS)
  99. python3 scripts/codex_run.py start TODO.md PROJECT --probe # docker backend: verifies confinement, no model call
  100. ```
  101. ## License
  102. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.