Skip to content

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 branch codex/<name>.
  • Codex can change files by default. For reviews, see "Reviews" below.
  • Add --background for long work. The run directory it prints holds exit-status and final-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

  1. One worktree per unit. scripts/codex-delegate.sh worktree <name> cuts codex/<name> from origin/main into .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.
  2. 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.
  3. Watch, don't poll by hand. A Monitor loop reads the newest .codex-delegate/runs/run.*/exit-status per worktree and emits a line only on change.
  4. 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 export GOCACHE=/tmp/elps-<name>-go-cache). A unit's "green" is a claim until the host has run the same command.
  5. 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.
  6. Sweep the moment the round is accepted: sweep <name>, then delete codex/<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 max or ultra tier.

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. uptime and df -h /; ps aux | grep app-server-broker shows 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-cache and /tmp/codex-*-cache directories of units that are swept or finished (no owner on their .codex-delegate/run.lock, checked with fuser). Never judge by age, and never delete a live unit's cache or worktree. go clean -cache goes 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 stash in 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>, or sweep alone 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.md before starting, and follow it.
  • Run make test && make static-checks && make elpsvet before 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(), and TestDefaultAnalyzers' count updated.
  • User-facing changes update docs/lang.md.
  • Never delete the //nolint:gosec directive on the last return of parser/token/token.go's Type.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 //nolint question 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.

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: 465kUpdated Claude CodeCodexVerifiedInstall
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: 465kUpdated Claude CodeCodexVerifiedInstall
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: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall