| name | headless-dispatch |
| description | Dispatch a Claude Code headless worker from a non-Claude harness such as Codex or Grok. Codex exposes fable-execute, opus-execute, sonnet-execute, deep-execute, and glm-execute as exact native command skills; all are one script and one --backend flag, mapped below. Use when asked to run a task on fable, opus, sonnet, deepseek, or glm from Codex, spawn a headless/background worker, or hand work off the main thread. Covers network egress, .git writability, doctor preflight, and shell invocation. |
| allowed-tools | ["Read","Bash","Glob","Grep"] |
headless-dispatch — spawn a Claude worker from Codex
claude-headless-exec is a plain bash script. You have a shell, so you can run
it.
Preflight — check this first, once per session
bash <plugin-root>/scripts/codex-doctor.sh
The doctor checks the plugin cache, local tooling, credentials, and two sandbox
preconditions — network egress and .git writability. Continue only when
both pass.
.git writability — the second sandbox precondition
Codex workspace-write treats .git as a protected path: read-only,
recursively, even inside an otherwise-writable root (upstream default,
documented under "Protected paths in writable roots"). A worker in that sandbox
cannot honor COMMIT-ON-RED, so its edits sit unowned until a peer's broad
git add adopts them.
Probe directly with test -w "$(git rev-parse --absolute-git-dir)".
If it is read-only, fix the sandbox — never the brief. Telling workers to
"run no git commands, the conductor commits" is a per-backend exemption written
into prose; it carries no scope marker and leaks onto backends it never applied
to (it did exactly that on 2026-07-20, reaching Claude workers that could commit
fine). Instead:
- Per-invocation, preferred when you control the launch:
-c 'sandbox_workspace_write.writable_roots=["<abs>/.git"]'
- Permanent: add the repo's
.git to [sandbox_workspace_write] writable_roots in the Codex configuration file. Unlike network_access = true,
this is path-scoped — list specific repos, never a wildcard — so it grants
nothing outside the repos you name. Still the human approver's call to make.
codex-headless-exec already grants this per-run, so a failure here means you
are on a launch path that bypasses it: interactive codex, a bare
codex exec, or a fresh machine with no global config.
The direct network probe is:
curl -s -o /dev/null -w "%{http_code}" --max-time 10 https://api.anthropic.com/v1/models
000 means your sandbox blocks DNS and every worker will die at rc=6.
STOP; do not dispatch a worker from this session. An already-running blocked
session cannot grant itself network access. Choose a policy and restart Codex:
- Prefer a narrow launch override when you control the Codex invocation:
-c sandbox_workspace_write.network_access=true. This grants network access
only to that invocation.
- Never edit global Codex configuration without the human approver's explicit approval.
A global
[sandbox_workspace_write] network_access = true permanently weakens
every workspace-write Codex session on this machine, across every project.
Do not attempt to work around the sandbox from the blocked session.
The *-execute commands are one script and one flag
Claude Code exposes /fable-execute, /opus-execute, /sonnet-execute,
/deep-execute and /glm-execute as five slash commands. They are not five
things. Each is a thin wrapper that ends up at the same script with a different
--backend. In Codex, $meta-dev:fable-execute and its peers are exact native
skills that adapt these command procedures. When already inside this skill,
run the script directly:
| Claude Code command | --backend | Model | Reach for it when |
|---|
/fable-execute | fable | claude-fable-5 | hardest tasks — max reasoning, long-horizon coherence |
/opus-execute | opus | claude-opus-5 | architecture, hardening, review, security |
/sonnet-execute | sonnet | claude-sonnet-5 | Anthropic judgment, off-thread |
/deep-execute | deep | deepseek-v4-pro (default, V4-Pro-0813 GA; --flash → deepseek-v4-flash; --vision → deepseek-v4-flash-vision-exp) | default reasoning worker; --flash for mechanical bulk; --vision for images |
/glm-execute | glm | glm-5.2 | long-horizon, stateful agentic refactors |
sonnet/opus/fable are real Anthropic via your ambient Claude login —
no API key. deep needs DEEPSEEK_API_KEY, glm needs GLM_API_KEY; the doctor
reports which are visible. All five pin a bare model ID (no [1m] — a no-op on first-party, where the 5-family is always 1M), so a
headless worker cannot inherit a session's 1M beta and get billed at the premium
rate.
Three commands are not on this script and take their own: /codex-execute →
codex-headless-exec, /grok-execute → grok-headless-exec,
/antigravity-execute (/agy-execute) → agy-headless-exec. Antigravity
default is Gemini 3.7 Flash (1M context, native multimodal, Search). --opus
there is Claude Opus 4.6 on Google quota, not Claude Code. Parked / named-only.
Full flag reference — the authoritative source, prefer it over this table when
they disagree:
bash <plugin-root>/scripts/claude-headless-exec --help
Invoke
bash <plugin-root>/scripts/claude-headless-exec \
--backend opus \
--repo app \
--effort high \
'<complete, self-contained task spec with acceptance criteria>'
Resolve <plugin-root> rather than hand-typing it — the cache path is
version-pinned and moves on every patch bump:
PLUGIN_ROOT="$(ls -d "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/meta-dev/meta-dev/*/ | sort -V | tail -1)"
--repo <alias> takes the lowercase alias (app/www/gallery/meta), never a
directory name. Add --readonly when the worker only investigates and reports —
a read-only worker cannot write, so handing it a code-writing task fails.
The worker shares no context with you: give it a complete, self-contained task
specification with acceptance criteria. What comes back is its final text plus a
manifest listing exactly the files it touched.
The worker commits its own scoped edits — that is harness law, not a per-task
choice. Never write "run no git command, the conductor commits" into a worker
spec; if a worker genuinely cannot commit, that is an executor to fix or a
routing decision, not prose to add. See the .git writability section above.
