luthersystems/elps / .claude/skills/codex-delegate
codex-delegate
Verified/codex-delegate — Codex Delegation Skill
Hands a bounded coding unit to OpenAI Codex in its own git worktree, with write access to the files, and takes the work back verified on the host.
Trigger
Use when asked to delegate work to Codex, to get a second opinion or an independent diagnosis from Codex, to fan out several Codex tasks at the same time, or when a Codex run says the broker is busy. Also covers the set-up this container needs, because the Codex login and the plugin do not survive a new session.
Use scripts/codex-delegate.sh. It calls the Codex plugin's own runtime
(codex-companion.mjs). It does not copy the plugin logic.
WARNING: the working tree may be the only copy
Codex CANNOT COMMIT in this sandbox: .git is read-only. Git cannot recover
unstaged edits destroyed by git checkout HEAD -- ., git restore,
git reset --hard, git clean, or git worktree remove --force. Never tidy
an active or uncollected unit's worktree. A transcript is not a backup.
The wrapper captures before launch, every second while monitoring, and before
and after teardown. Each run's current symlink points to a complete immutable
snapshots/snapshot-* directory. tracked.patch includes staged and unstaged
changes and binary payloads relative to base.commit; untracked/ preserves
nonignored new files and symlinks. untracked.paths0 is a NUL-delimited manifest.
Earlier snapshots are retained even if a later command removes the changes.
A failed capture leaves the previous snapshot available and prints an error.
To recover, select a snapshot containing the work, create a separate clean
worktree at the commit in its base.commit, apply its tracked.patch with
git apply, then copy untracked/. into that worktree with cp -a. Inspect
and commit the recovered work from an environment that can write .git.
After SIGKILL, exit-status and the final message may be absent: look in
snapshots/ and in runs/recovery.* before touching the source worktree.
Snapshots are best-effort reads during editing, not a transaction across all
files. Edits since the last successful capture, ignored files, and files in
submodule worktrees are not protected. Copy bundles off-host for host/disk loss.
Retained snapshots cost disk; remove them only after accepting and securing the
unit's work. Use sweep for retired worktrees: it takes the same workspace lock,
captures before cleanup, and archives both work and previous run bundles under
the wrapper repository's .codex-delegate/swept/ before removing the worktree.
Capture, archive, or teardown failure refuses removal.
All cleanup must use the wrapper or its runtime reap command, which takes the
same run.lock. Never kill brokers by hand while launching work into their
workspace. The lock cannot coordinate arbitrary external kill/Git commands
or plugin launches that bypass the wrapper. --allow-busy explicitly bypasses
this protection and must not be used to work around cleanup in progress.
Worktrees start from the locally recorded remote default (origin/HEAD, or
origin/main if the symbolic ref is absent). Existing branches/worktrees must
contain that tip and origin/main when present; stale/diverged bases are refused.
The wrapper does not fetch: update remote-tracking refs separately before
launching if their freshness is unknown. Missing remote refs cause refusal.
First, prove the container is ready
The Codex login and the plugin live in the container. A new session loses both. Always start here:
./scripts/codex-delegate.sh preflight
If it says the plugin is missing, or Codex is not logged in, do the set-up in "Set up a fresh container" below before anything else.
Send one task
./scripts/codex-delegate.sh run --worktree <name> "<the task>"
--worktree <name>makes (or re-uses) a git worktree in.claude/worktrees/<name>on a branchcodex/<name>.- Codex can change files by default. For reviews, see "Reviews" below.
- Add
--backgroundfor long work. The run directory it prints holdsexit-statusandfinal-message.txt; collect them as in "The loop, as run".
Other options: --dir <path>, --model <name|spark> (see "Models"),
--effort none|minimal|low|medium|high|xhigh, --resume.
The loop, as run
- One worktree per unit.
scripts/codex-delegate.sh worktree <name>cutscodex/<name>fromorigin/maininto.claude/worktrees/<name>. To build on a feature branch, cut it by hand (git worktree add .claude/worktrees/<name> -b codex/<name> <branch>) and pass--dir. - Launch in the background.
run --dir <worktree> --background <model flags from "Models"> "$(cat brief.md)"returns a job id and the run directory at once. - Watch, don't poll by hand. A
Monitorloop reads the newest.codex-delegate/runs/run.*/exit-statusper worktree and emits a line only on change. - Read
final-message.txt, then verify on the host — always. The sandbox cannot open sockets, write the shared git index (units never commit), or write the default Go cache (units exportGOCACHE=/tmp/elps-<name>-go-cache). A unit's "green" is a claim until the host has run the same command. - Commit on the unit's branch yourself, message in the repo's style — a plain sentence saying what changes and why, never a model identifier.
- Sweep the moment the round is accepted:
sweep <name>, then deletecodex/<name>and/tmp/elps-<name>-go-cache.
Models
- Default:
--model gpt-6.1-sol --effort xhigh. - Hard work (deep diagnosis, a subtle interpreter change):
--model gpt-6-astra --effort high. - Never a
maxorultratier.
Other sections refer here rather than repeating model names.
Reviews
A review runs in normal write mode, in its own worktree, with its own Go
cache. For a review of main, let the wrapper make the worktree; it refuses a
stale or diverged base:
./scripts/codex-delegate.sh run --worktree <name> --background \
<model flags from "Models"> "$(cat brief.md)"
# brief says: export GOCACHE=/tmp/elps-<name>-go-cache before any go command
To review a PR branch, make the worktree by hand: git fetch origin first,
pick a unique <name> (-b fails if codex/<name> already exists), then
git worktree add .claude/worktrees/<name> -b codex/<name> origin/<pr-branch>
and pass --dir .claude/worktrees/<name>. It lives under .claude/worktrees,
so sweep <name> retires it.
Observed behaviour: under --read-only the sandbox could not run tests or
write /tmp, so a review there can only read code. Put "do not edit files" in
the brief if edits are unwanted, and verify its findings on the host. Use only
the wrapper; do not build a custom sandbox.
The brief
Keep it self-contained. A short template:
Read AGENTS.md first, then .claude/skills/<skill>/SKILL.md, and follow them.
Before any go command: export GOCACHE=/tmp/elps-<name>-go-cache
FAILURE (verbatim): <test name / CI lines / gate output>
Start reading at: <file>:<line>
The fix must: <rule it satisfies>
The fix must NOT: <what is off limits, e.g. touch other packages, drop a nolint>
Verify with exactly: go test ./<pkg>/... ; make static-checks ; make elpsvet
If the sandbox cannot run a command, say which and why. Never claim green.
Do not commit; leave the changes in the worktree.
Report: root cause; files changed; each command with its verbatim output;
anything you are unsure of.
Continuing a thread
run --dir <worktree> --resume "<follow-up>" continues the last Codex thread
for that workspace: answer a question a unit stopped on, hand back a review
finding, or hand back host results the sandbox could not produce. If it fails
with "Task ... is still running" (the plugin's registry kept a unit killed
earlier), launch a fresh run with the same brief plus the follow-up; the
worktree already holds the code.
Send several at the same time
Give every subagent its own --worktree name. This is not only tidiness:
The plugin keys its Codex broker on the workspace root. Two tasks in the SAME directory share one broker and can collide. Two tasks in DIFFERENT worktrees each get their own broker.
Keep each subagent a thin forwarder, which is how the plugin's own
codex-rescue agent works: make one run call, give back what Codex said, and
add no analysis of your own. This keeps Codex's answer independent of Claude's.
Verify on the host
make test # Go tests plus the example lisp files
make static-checks # golangci-lint with gosec; CI's version is the authority
make elpsvet # elps's own Go analyzers, two passes
go test ./lisp/... # the interpreter core alone, for a narrow unit
Rules this container taught us
- Check before a wave.
uptimeanddf -h /;ps aux | grep app-server-brokershows units already running (other sessions count). Keep heavy units to about 3 at a time; more drives load high enough that everything slows or times out. - Watch the disk. The script refuses to start below 8 GB free. A unit that
vanishes or a subagent that stops reporting is almost always disk. Clear, in
order:
.codex-delegate/swept/archives of accepted work, then the/tmp/elps-<name>-go-cacheand/tmp/codex-*-cachedirectories of units that are swept or finished (no owner on their.codex-delegate/run.lock, checked withfuser). Never judge by age, and never delete a live unit's cache or worktree.go clean -cachegoes last, and only when no unit is running. - Stale brokers. Retire them with
sweep <name>, which stops the workspace's broker under the lock. Do not kill brokers or delete broker temp directories by hand. - Never
git stashin any worktree. The stash list is shared by every worktree of the repo; a pop in one can apply another checkout's stash. - One Codex unit per PR or item. Do not fold unrelated items into a unit.
- Sweep when an agent retires.
./scripts/codex-delegate.sh sweep <name>, orsweepalone for all of them. Do this as each agent finishes, not later. - "Broker is busy" is not an error. It is a start-up race. The script retries it three times. Never read it as a login failure.
- Never run git in a worktree while another process watches
.git. A worktree in.claude/worktrees/shares the same.git.
What Codex does not know
Do not assume Codex has read AGENTS.md or the skills. Put the rules it must obey into the task
text, or read its diff before you keep the work. The ones a brief must cite:
- Read the matching
.claude/skills/*/SKILL.mdbefore starting, and follow it. - Run
make test && make static-checks && make elpsvetbefore handing back (the full gate is.claude/skills/verify/SKILL.md). - Every new builtin, special operator, or macro needs a docstring; CI runs
elps doc -m. - A new form with structural requirements needs a lint analyzer registered in
DefaultAnalyzers(), andTestDefaultAnalyzers' count updated. - User-facing changes update
docs/lang.md. - Never delete the
//nolint:gosecdirective on the lastreturnofparser/token/token.go'sType.String. It is load-bearing under CI's golangci-lint; a local lint run reporting it as unused is version skew, not a finding. Settle any//nolintquestion against CI's pinned version, not against whatever is on PATH. - Commit messages are plain sentences saying what changes and why.
Codex writes files but it does not commit. Committing and pushing stays a separate, deliberate step.
Set up a fresh container
npm install -g @openai/codex
claude plugin marketplace add openai/codex-plugin-cc
claude plugin install codex@openai-codex
codex login --device-auth # prints a URL and a code to approve
codex login --device-auth is the only login that works here. The normal
codex login sends the browser to a localhost address inside the container,
which nobody outside can reach. There is no long-lived secret in this
environment: the login is per session, and a new container repeats it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |