Codex Scheduler

codex-scheduler

A job system for Codex, layered on top of the codex-subagent skill's proven codex app-server plumbing. Use this instead of driving codex exec/codex_session.py by hand whenever you have more than one Codex job, jobs that depend on each other, or you want to keep working while a job runs instead of babysitting it.

One global daemon (auto-started on first use) runs jobs from every workspace and every concurrent Claude session against a shared SQLite DB at ~/.claude/codex-scheduler/db.sqlite3. It enforces a parallelism limit (default 3), respects a dependency graph between jobs, and never silently retries a failed job.

The core loop: submit, then get notified — don't poll

Always submit, then launch wait --drain via the Bash tool with run_in_background: true. That's what makes this different from raw codex exec/codex_session.py: Claude Code natively delivers a <task-notification> to the session that started a backgrounded Bash command when it exits. wait blocks on the shared DB until your jobs finish, then exits — so you get told, unprompted, the moment Codex is done or breaks, instead of having to remember to check.

python3 .claude/skills/codex-scheduler/scripts/scheduler_cli.py submit \
  --session <this-claude-session-id> --slug fix-lint --workspace <abs-repo> \
  --prompt "Fix the lint errors in src/" --effort xhigh

# THEN, via Bash with run_in_background: true:
python3 .claude/skills/codex-scheduler/scripts/scheduler_cli.py wait \
  --session <this-claude-session-id> --drain

Nothing can arm the watcher for you — so submit tells you whether one is armed

A <task-notification> is produced only when a Bash command you backgrounded exits. The scheduler cannot self-arm that from inside the daemon, which makes "forgot to arm a watcher" a silent failure: jobs run, finish, write their results to the DB, and nobody is ever told. This has bitten real sessions — six jobs once sat finished and unreported because a dispatch went out with no watcher behind it.

So every submit/submit-batch now prints your notification status:

  watcher: armed for this session
  watcher: NONE ARMED -- you will NOT be notified when this finishes.
           Background this via the Bash tool with run_in_background: true:
             python3 .../scheduler_cli.py wait --session <id> --drain

If you see NONE ARMED, arm one before you walk away.

Use --drain, not a re-arm treadmill

Plain wait returns as soon as one job settles — --follow only changes how messages are streamed, not that. Dispatch five jobs and you must re-arm five times, and every gap between them is a window where a finishing job notifies nobody. That is precisely how sessions lose results.

--drain reports each job as it settles and keeps going, exiting only once the session has had nothing queued or running for --idle-grace seconds (default 30). One watcher covers an entire dispatch, including jobs submitted after it was armed — the grace period exists because an early job often settles in the gap before the next submit lands, and exiting there would strand the rest.

You'll get a <task-notification> with wait's stdout: the job's slug, final status, and its result text (or error). If your session ends/restarts before that happens, scheduler_cli.py list --session <id> catches you up on anything you missed.

Get <this-claude-session-id> from your own session id (visible in your environment/context); pass it consistently on every submit/wait for that job so jobs are attributed correctly.

Submitting a batch with dependencies

For a DAG of jobs, submit them all at once as JSON and reference dependencies by slug:

Each job spec takes either an inline "prompt" or a "prompt_file" (path to a file with the full brief — relative paths resolve against the directory containing --file, handy for keeping long briefs out of the JSON):

cat > /tmp/jobs.json <<'EOF'
[
  {"slug": "gen-a", "prompt": "...", "workspace": "/abs/repo", "effort": "xhigh"},
  {"slug": "gen-b", "prompt_file": "gen-b-brief.md", "workspace": "/abs/repo", "effort": "xhigh"},
  {"slug": "merge", "prompt": "...", "workspace": "/abs/repo", "deps": ["gen-a", "gen-b"]}
]
EOF
python3 .../scheduler_cli.py submit-batch --session <id> --file /tmp/jobs.json
python3 .../scheduler_cli.py wait --session <id> --slugs gen-a,gen-b,merge --all   # (backgrounded)

merge only starts once both gen-a and gen-b are done. If a dependency fails, its dependents are automatically marked failed too (never retried, never left stuck queued) — check show <slug> for the error field explaining why.

For a batch, prefer one wait --drain over --slugs ... --all: --all reports the set in a single burst only once every slug is terminal, whereas --drain reports each job the moment it lands and still covers anything you add later.

Codex can message you back mid-run

Every job's prompt automatically gets a short preamble telling Codex it can send you an ad-hoc message without ending its turn, by running:

python3 .../scheduler_cli.py notify <its-own-slug> "<message>"

This goes through the same channel as job completion — the next wait for that session returns it immediately (before the job itself finishes), tagged as a message rather than a result, and it also appears live in the dashboard's output panel. Use it for jobs where you want an early heads-up, a question, or a checkpoint instead of waiting for the whole turn — no need to explain the mechanism yourself, Codex is already told about it.

Correction (2026-09-01): the earlier note here blamed Codex for ignoring this preamble. That was wrong, or at least incomplete. notify writes to the scheduler's SQLite DB, which is outside the job's sandbox, so from inside a read-only or workspace-write job the command was rejected by the sandbox — indistinguishable, from the outside, from Codex declining to call it. Codex was often trying and failing. Use the [[NOTE]] marker instead (see "Checkpoints" below): it travels in the message stream, needs no filesystem access, and works in every sandbox. Instruction-following still varies with effort, but that is now the only variable rather than the second of two.

Command reference

All commands: python3 .claude/skills/codex-scheduler/scripts/scheduler_cli.py <cmd> ...

steer/stop/rm/edit/reorder only act on the job's most recent active (queued/running) row for that slug — a slug can be reused once its earlier job is terminal.

Continuing a finished job

Rule (Fabian, 2026-09-07): a restarted, continued or corrected epic reuses the same Codex session. Every follow-up turn on an epic is submitted with --resume-from <previous slug of that epic> (or --resume-thread <id>), never as a fresh job. A fresh job is only for different work, or when a second, independent opinion is wanted on purpose. list shows the lineage in the THREAD column: = e16-epic means the job runs in the same Codex session as e16-epic; new means a fresh session. The job id and slug change per turn, the thread does not.

submit --resume-from <slug> starts a new job inside the finished job's Codex thread instead of a fresh one, so the model still has everything from that turn: what it read, what it decided, what it already wrote, plus the prompt cache behind it (the verification run's second job billed 14.3k input tokens of which 13.1k were cached).

python3 $CLI submit --session <sid> --slug e12-s2 --workspace /path/to/repo \
  --prompt-file slice2.md --resume-from e12-s1

Use it for the next chunk of the same epic, a correction to work a job just did, or a follow-up question about what it found. Reach for a fresh job instead when the task is unrelated — a long thread carries irrelevant context and costs tokens on every turn.

• The source job must belong to the same Claude session and be terminal (done, failed or stopped), and must have a recorded thread_id. Anything else is refused with the reason.
• --resume-thread <thread id> does the same from a raw Codex thread id, for a thread this scheduler's DB doesn't know about. The two flags are mutually exclusive.
• The resumed job is a normal job: its own row, slug, log and result, so list, show, wait, steer and stop behave exactly as usual. show <slug> prints resumed from: <slug> (thread …).
• The sandbox, model and cwd come from the thread you resume. Codex re-applies the resumed thread's own settings, so passing a different --sandbox/--model on the resuming job is not a reliable way to change them — submit a fresh job if you need different ones.
• Context window limits still apply. A resumed thread keeps growing and compacts itself when it fills, so a very long chain gradually loses its earliest detail. For a long epic, prefer a few resumed chunks over dozens.
• Codex, OpenCode and OMP only — --engine cursor jobs have no resumable thread. An OpenCode or OMP job resumes its session (opencode run --session <id> / omp -r <id>) with the same flags and the same lineage display; a thread/session can only be continued on the engine that created it.
• In a submit-batch file the same thing is "resume_from": "<slug>" (or "resume_thread": "<id>") on a job spec. The source must already be terminal at submit time, so it cannot be another job in the same batch.

Protocol note: this issues thread/resume ({threadId, cwd, approvalPolicy}) before the usual turn/start, confirmed against codex app-server generate-json-schema (ThreadResumeParams, codex-cli 0.153.4). If the resume fails the job fails with that error rather than quietly starting a fresh thread.

Goal mode

The goal is the finish line; the prompt file is the requirements. A normal job ends when its one turn ends, whether or not the work is actually finished. A goal job carries a thread-level goal, keeps taking turns in the same thread, and ends when the goal is reached.

python3 $CLI submit --session <sid> --slug e12-epic --workspace /path/to/repo \
  --prompt-file specs/e12/brief.md \
  --goal-file specs/e12/goal.md --goal-budget 2000000 --goal-max-turns 12 \
  --model gpt-6-astra --effort medium --sandbox danger-full-access

• --goal-file <path> (or --goal "<text>", mutually exclusive) is the objective. Write it as a verifiable end state, not a task list: "every slice of the spec is implemented and PAO_DISABLE=1 php artisan test tests/Feature tests/Unit is back at the known baseline".
• --goal-budget <tokens> is the thread's token budget. Running out settles the job rather than letting it grind on.
• --goal-max-turns N (default 12) caps how many turns the scheduler will let the goal run for.
• Codex engine only. --engine cursor, --engine opencode and --engine omp have no thread goal and the submit is refused.

What the status column means. list shows goal:<status>/<n>t — the goal's status and the number of turns taken. The status vocabulary is the protocol's own (ThreadGoalStatus: active, paused, blocked, usageLimited, budgetLimited, complete) and it maps to a job outcome like this:

blocked is a real job status: wait returns on it like any other terminal status, and a queued dependent of a blocked job is failed the same way it would be for a failed dependency.

show <slug> prints the objective, status, tokens used against the budget, wall time and turn count. wait --json carries the same under a goal key.

Who drives the turns. Verified live (2026-09-07, codex-cli 0.153.4): the app-server itself starts the next turn while a goal is active. The scheduler waits 8 seconds after turn/completed and only starts a turn of its own if the app-server did not — the log line [goal: app-server started the next turn itself; not double-starting] is that guard firing. Turns the scheduler starts itself open with one fixed nudge, "Continue toward the goal. Report what is verified so far."

Resuming keeps the goal. --resume-from <slug> on a goal job reads the goal already on the thread (thread/goal/get) instead of re-setting it, so the tokens and time already spent carry over. Passing a new --goal-file/--goal on the resuming job replaces the objective deliberately.

Protocol: thread/goal/set {threadId, objective, status, tokenBudget} after thread/start / thread/resume and before turn/start; thread/goal/updated is persisted on every change.

Worktrees per epic

submit --worktree runs the job in its own git worktree instead of the shared checkout, so two lanes on the same repo cannot overwrite each other's files.

python3 $CLI submit --session <sid> --slug e12-epic --workspace /Users/you/repo \
  --prompt-file brief.md --worktree --sandbox danger-full-access

• The worktree is <workspace>/.claude/worktrees/<slug> on a new branch lane/<slug>, cut from the current main HEAD (from HEAD if the repo has no main). An existing worktree or branch of that name is reused, never recreated.
• workspace on the job row stays the main checkout; worktree_path is what the job actually runs in. list shows the worktree path in the WORKSPACE column and show prints the branch.
• A fresh worktree is bare, so submit prepares it and prints what it did: vendor is cloned from the main checkout (APFS clone cp -c -R on macOS, cp -R --reflink=auto on Linux, plain copy otherwise) and composer dump-autoload --no-interaction runs in the worktree when it has a composer.json; node_modules is symlinked; .env is copied with a sqlite DB_DATABASE= rewritten to <worktree>/database/database.sqlite, and the main checkout's database/database.sqlite is copied to that path. --no-symlinks skips all of that.
• Why vendor is never a symlink. Composer writes vendor/composer/autoload_psr4.php with $baseDir = dirname($vendorDir) resolved from the real path, so a symlinked vendor makes the worktree autoload App\ and Tests\ out of the MAIN checkout: every test run inside the worktree silently exercises main's code instead of the branch's, and passes. (Found in daemons.run on 2026-09-08.) The clone is nearly free on a copy-on-write filesystem, and the dump-autoload afterwards rewrites those paths for the worktree. node_modules has no such problem, because Node resolves modules relative to the real file's location, so it stays a symlink and stays free.
• --resume-from inherits the source job's worktree, so every turn of an epic lands in the same tree. If that worktree has since been removed the submit is refused rather than silently running in the main checkout.
• Nothing is ever removed automatically. worktree-list --workspace <repo> shows what exists; worktree-remove <slug> --workspace <repo> removes one (refusing while a queued/running job still uses it, unless --force). The lane/<slug> branch is always kept — delete it yourself.
• In a submit-batch file: "worktree": true (and "no_symlinks": true) on a job spec.
• Merging is yours: the lane commits on lane/<slug>, and you review and merge it into main.

Getting output you can act on

--schema: make the result machine-readable

Pass a JSON Schema (inline, or a path to a .json file) and Codex is told its final message must be exactly one JSON value matching it:

python3 .../scheduler_cli.py submit --session <id> --slug audit --workspace <repo> \
  --schema '{"type":"object","required":["findings"],"properties":{"findings":{"type":"array"}}}' \
  --prompt "Audit X. Return findings as JSON."
python3 .../scheduler_cli.py wait --session <id> --slugs audit --all --json

The daemon parses the final message (tolerating a ```json fence or surrounding prose), checks it, and stores it in result_json, which wait --json returns as real JSON. On a mismatch the job still completes -- result keeps the raw text and schema_error says what was wrong, so you never silently lose the work.

The check is deliberately shallow: top-level type plus required keys. It catches the common failures (answered in prose, dropped a field) and nothing subtler. It is not a JSON Schema validator, so do not treat a pass as full validation of nested structure.

--cite: make claims checkable

Adds a preamble requiring every factual claim in the result to carry an anchor you can verify independently -- file.py:120-134 for code, URL plus the quoted sentence for a web source, the exact command and its output for observed behaviour -- and to mark anything it cannot anchor as UNVERIFIED rather than dropping it or dressing it up.

Use it whenever you intend to act on the result. Verification is the real bottleneck on delegation: a claim you can spot-check in seconds is worth far more than a confident paragraph you would have to redo the work to trust.

{{deps.<slug>.result}}: pass work down the graph

Dependencies sequence jobs; interpolation lets them actually compose. In any prompt:

• {{deps.<slug>.result}} -- that dependency's final result
• {{deps.<slug>.result_json}} -- its validated structured result
• {{deps.<slug>.checkpoint}} -- its last checkpoint

Substitution happens at launch, once the dependency is done, so the downstream job sees the real text instead of re-deriving it. An unknown slug is left in place verbatim and logged rather than silently blanked -- a visible {{deps...}} in a prompt is a bug you can see; an empty string is not.

Supervising a job while it runs

ask: a real question, and an answer

python3 .../scheduler_cli.py ask my-job "Which file are you on, and what have you ruled out?"

Blocks (default 120s) and prints Codex's reply. The question is steered into the running turn and the daemon captures the next agent message as the answer; Codex keeps working, the turn does not end, and the answer is not part of the job's result. Verified round-trip in testing: ~7s.

This is the tool for "is it on the right track?", because the progress log shows you what a job did and never what it concluded.

watch: get woken only when it matters

# (background this) wake on a dangerous command, or on a genuine stall
python3 .../scheduler_cli.py watch my-job --match "rm -rf|git push" --flat-for 90

Exits on the first of: --match hitting new log output, --flat-for seconds without the log growing (a real stall), the job settling, or --timeout. Because Claude Code notifies the session when a backgrounded command exits, this replaces polling the log on a timer -- which costs a full model invocation per tick, usually just to learn that nothing changed.

What the log can and cannot tell you: every shell command is visible (truncated to 200 chars), and so is every streamed message. Reasoning is not -- it appears only as a bare [item reasoning] marker, and web searches log neither query nor results. So a job reading the wrong repo is obvious within seconds, while a job reasoning its way to a wrong conclusion looks identical to one reasoning correctly. A stalled job shows a log that stops growing entirely; a thinking job keeps emitting markers at a slow, steady rate. Use --flat-for, not marker counts.

Checkpoints: surviving a stop

Jobs with --max-seconds, or at xhigh/ultra effort, are told to save progress periodically by writing a marker into their own message text:

[[CHECKPOINT]] read db.py and daemon.py; state machine mapped; still to do: cli, client

The marker must start a line (leading whitespace is fine) and its content runs to the next blank line. The scheduler stores it (replacing the previous checkpoint), strips it from the result, and surfaces it automatically when the job is stopped, times out, or exceeds its budget -- turning "all work lost" into "here is where it got to". [[NOTE]] <text> works the same way for an ad-hoc message to you, delivered through wait like notify.

The line anchor matters: a job that merely mentions the syntax mid-sentence -- "write a line starting with the [[NOTE]] marker" -- keeps that text in its result instead of having it parsed as a real message and cut out. (A marker starting a line inside a fenced code block is still treated as real; that case is rare enough to live with.)

Why markers rather than a CLI call. notify/checkpoint/answer all write to the scheduler's SQLite DB, which lives outside the job's sandbox. Under read-only -- and under workspace-write before this was fixed -- those writes are rejected, so the callback fails silently and looks exactly like Codex ignoring the instruction. (This was a real, long-standing bug: workspace-write jobs now get the scheduler state dir added as a writableRoots entry, but read-only has no writable path at all in the protocol.) The markers need no filesystem access whatsoever, so they work identically in every sandbox -- prefer them; the CLI forms remain for danger-full-access jobs and external callers.

Budgets and token accounting

--max-seconds N stops a job once it has run that long, recording budget exceeded as the cause and preserving its checkpoint. This is deliberately distinct from the hang timeout: a job can be perfectly healthy and still not worth more time.

Every job's cumulative token usage is captured live from the app-server (thread/tokenUsage/updated) and reported by wait and wait --json: input, cached, output, reasoning, total, and the model's context window.

Checking the Codex account

python3 .../scheduler_cli.py usage          # human-readable
python3 .../scheduler_cli.py usage --json   # full payload

Shows the plan, each rate-limit bucket with a used-percent bar and when it resets, credit balance, available reset credits, and lifetime/daily token usage. It queries Codex directly (account/rateLimits/read, account/usage/read) and deliberately does not start the scheduler daemon, so it is safe to run at any time -- including before deciding whether to fan out a batch of expensive jobs.

Choosing the engine: Codex, Cursor, OpenCode or OMP

Every job runs under one of four agent CLIs, selected with --engine (default codex). All are driven through the same scheduler: dependencies, --drain, budgets, checkpoints, markers, structured output and token accounting all work identically, and a batch can mix them freely -- including passing a Codex job's result into a Cursor job with {{deps.<slug>.result}}.

# Cursor with Composer (no reasoning levels -- one tier)
... submit --engine cursor --model composer-2.5 --slug build --workspace <repo> --prompt "..."

# Cursor with Grok 4.6, non-fast, choosing the reasoning level
... submit --engine cursor --model cursor-grok-4.6 --effort xhigh --slug review ...

# Cursor with Gemini 3.8 Flash, choosing the reasoning level (low/medium/high; no xhigh/max tier)
... submit --engine cursor --model gemini-3.8-flash --effort high --slug review ...

Model and reasoning level. Cursor bakes the reasoning level into the model id, so --effort selects the suffix rather than a separate parameter:

Families differ -- Grok 4.6 stops at xhigh, Gemini 3.8 Flash stops at high, Luna and Sol also offer max -- so resolution is checked against cursor-agent --list-models rather than assumed, and submit fails immediately with the available ids if a pairing does not exist. The resolved id is echoed on submit (model=cursor-grok-4.6-xhigh) so there is never doubt about what a job actually ran. Jobs are non-fast unless you pass --fast. --effort max and ultra are equivalent for Cursor (there is no tier above max, so both just reach for the ceiling a family actually has).

Differences worth knowing before choosing Cursor:

• No mid-turn control. cursor-agent -p is a one-shot process with no channel to inject into a running turn, so steer and ask are rejected with a clear message rather than silently dropped. stop still works (it terminates the process).
• Reasoning is visible. Cursor streams thinking text into the log; Codex emits only a marker. Cursor jobs are genuinely easier to supervise with watch.
• Sandbox mapping. read-only runs in Cursor's plan mode (read-only by construction); workspace-write and danger-full-access pass --force so a headless run never stalls waiting for an approval nobody is there to give.
• Tokens arrive once at the end rather than incrementally, and Cursor reports no context-window figure, so that field stays null.

OpenCode engine

--engine opencode drives opencode run --format json --model <provider/model> --dir <workspace> "<prompt>" — a one-shot subprocess streaming newline-delimited JSON events, like Cursor.

... submit --engine opencode --slug spike --workspace <repo> \
    --sandbox danger-full-access --prompt-file brief.md
# follow-up in the SAME OpenCode session
... submit --engine opencode --slug spike-2 --workspace <repo> \
    --resume-from spike --prompt "..."

When to use it (owner): only when Codex is exhausted (rate limit or credit) and the Claude budget is gone too, or when a deliberately different model is wanted for a second opinion. It is not a routine lane; the routing table above still decides normal work.

• Model: defaults to opencode/muse-spark-1.3-contributor-free — the OpenCode Zen free tier the UI labels "Muse Spark 1.3 Free". The opencode-go/…-contributor ids are a paid plan and must never be the default; pass one explicitly only if the owner asked for it. --model is validated against opencode models at submit time, so a typo fails immediately with the ids that do exist. --effort is recorded but means nothing here (no reasoning-level suffixes), and --fast is rejected as the Codex-only service tier it is.
• No sandbox at all. opencode run has no sandbox flag: tools run against the real filesystem with whatever the user's OpenCode config permits. danger-full-access is the only honest label, and submitting with anything else prints a note saying the value is recorded but not enforced. Do not send an OpenCode job work you would only trust to read-only.
• Resumable. Every event carries a sessionID; the driver stores it on the job like a Codex thread id, so --resume-from continues the session with its context and prompt cache (verified: the follow-up answered from memory with 13.5k of 13.9k input tokens served from cache).
• No mid-turn control, same as Cursor: steer and ask are rejected with a clear message, stop terminates the process.
• No goal mode (--goal/--goal-file is refused; only Codex has a thread goal).
• Markers work identically: [[NOTE]]/[[CHECKPOINT]] lines are dispatched and stripped, the final assistant message becomes the result, tool calls are logged one line each, and tokens are reported from the last step_finish event (input/cached/output/reasoning; no context-window figure, so that field stays null). A nonzero exit or an error event fails the job with the message OpenCode gave.

OMP engine

--engine omp drives omp -p --mode json --model opencode-go/deepseek-v4.1-flash --thinking high "<prompt>" — a one-shot subprocess streaming newline-delimited JSON events, like Cursor and OpenCode. It is scoped to exactly one model at exactly one reasoning level: DeepSeek v4.1 Flash, high thinking. That is a deliberate, narrow deployment, not a placeholder -- nothing else has been wired up or validated for this engine.

... submit --engine omp --slug spike --workspace <repo> \
    --effort high --sandbox danger-full-access --prompt-file brief.md
# follow-up in the SAME omp session
... submit --engine omp --slug spike-2 --workspace <repo> \
    --resume-from spike --prompt "..."

• Model and effort are fixed. --model (if passed) must resolve to opencode-go/deepseek-v4.1-flash (a bare deepseek-v4.1-flash is also accepted); anything else fails at submit time. --effort must be high (the model's other levels, low/max, are not wired up); anything else fails at submit time too. --fast is rejected as the Codex-only service tier it is.
• No sandbox at all, same as OpenCode: omp has no sandbox flag, tool calls run against the real filesystem gated only by --auto-approve. danger-full-access is the only honest label; submitting with anything else prints a note saying the value is recorded but not enforced.
• Resumable. Every run prints a session event with a uuid; the driver stores it on the job like an OpenCode session id, so --resume-from continues the session with its context and prompt cache (verified: a follow-up answered from memory with the bulk of input tokens served from cache).
• No mid-turn control, same as Cursor/OpenCode: steer and ask are rejected with a clear message, stop terminates the process.
• No goal mode (--goal/--goal-file is refused; only Codex has a thread goal).
• Markers work identically: [[NOTE]]/[[CHECKPOINT]] lines are dispatched and stripped, the final assistant message becomes the result, tool calls are logged one line each, and tokens are reported from the turn_end event's usage (input/cached/output/reasoning; no context-window figure, so that field stays null). A nonzero exit or a non-JSON stdout line fails the job with that text as the error.

Job parameters

• effort: low | medium | high | xhigh | max | ultra — Codex's own reasoning-effort vocabulary, low to high (verified against ~/.codex/models_cache.json and live codex exec calls at every level, 2026-09-04). Scale to the job like the base skill's recipes: low for quick lookups, high/xhigh for real analysis, max/ultra for the hardest code tasks — ultra additionally triggers Codex's own automatic task delegation.
• model: defaults to gpt-5.6-sol. For the hardest jobs, --model gpt-6-astra (a full generation up, not a 5.6-family sibling — "our most capable model for complex, demanding work" per Codex's own listing) is worth the extra cost/latency; pair it with --effort high/xhigh/max/ultra. Verified working end to end 2026-09-04. At the other end, Codex also exposes cheaper/faster 5.6-family siblings for lower-stakes jobs — e.g. gpt-5.6-luna (verified working via codex exec -m gpt-5.6-luna) — pass --model gpt-5.6-luna when you don't need the default tier.
• fast_mode (--fast, default off): sets Codex's service_tier=fast + features.fast_mode=true for that job's app-server process — ~1.5x speed at a higher credit rate (2.5x standard on GPT-5.6/5.5, 2x on GPT-5.4). It's a speed/cost tradeoff, independent of effort — use it when wall-clock time matters more than credit spend for that specific job.
• sandbox: read-only | workspace-write (default) | danger-full-access, same semantics as codex exec -s. Which one do you need? workspace-write blocks network access, TCP/Unix sockets, and writes to .git — it's for straightforward file edits only. If the job stages files (git add), drives a browser or emulator, runs anything socket-based (a local server, a test harness that binds a port), or fetches something over the network, use --sandbox danger-full-access instead. A workspace-write job that silently hits one of these restrictions usually doesn't error cleanly — it just produces a wrong/empty result with no obvious cause, so get the sandbox right up front rather than debugging it after the fact. The submit confirmation and list/show always echo the sandbox actually used, specifically so a wrong choice is visible immediately instead of discovered hours later.
• schema / cite / max_seconds: see "Getting output you can act on" above.
• No auto-retry: a failed/hung job is marked failed and reported as-is — the scheduler never silently resubmits it. Decide whether to submit it again yourself after seeing why it failed (show <slug>).
• Invalid model names don't fail cleanly (verified 2026-08-31): unlike codex exec, which rejects an unknown -m with a clear 400 error, codex app-server accepts it, runs the turn, and reports turn/completed with an empty result — the job shows status: done, result: "". If a job comes back done with an empty/near-empty result, suspect a typo'd --model first.

Steering and stopping

steer/stop reuse codex_session.py's already-verified file control plane — the daemon drives each running job's codex app-server process itself and polls that job's <jobdir>/control file for steer:/interrupt/quit lines, exactly like the base skill's session daemon.

Dashboard

Auto-started at http://localhost:1234 the first time the daemon (re)starts in a session — you don't need to run anything to get it. scheduler_cli.py ui [--port N] starts/reuses it explicitly (e.g. for a different port); it detects and reuses an already-running instance on that port instead of double-starting. A small, stdlib-only HTTP server (no external dependencies) showing a live-updating job table; click a row to expand it and live-tail that job's log. Each running job's row has a Cancel button — it stops that job exactly like scheduler_cli.py stop would, and records "stopped by the user via the dashboard" as the cause, so the next wait for that job tells you plainly that the user did it, not that it failed.

The table's "Working On" column (running jobs only) is a one-line, plain-language summary of what a job is doing right now — e.g. "Currently testing the Android mobile app" — regenerated about once a minute per running job by a separate, cheap codex exec -m gpt-5.6-luna -c model_reasoning_effort=low call fed the job's own recent (filtered) output. It's a nice-to-have, not something to depend on for anything besides a glance at the table.

The dashboard is a static page that polls for data, not one that hot-reloads its own code — if this skill's static/index.html changes (e.g. after an update to this skill), your browser tab needs a manual reload to pick up the new JavaScript; the live-updating table/log you already have open won't do that on its own.

Notes

• One global daemon and DB serve every workspace — job workspace is just each job's own cwd for Codex, independent of where the daemon itself runs.
• Runtime state (DB, pidfile, per-job logs) lives at ~/.claude/codex-scheduler/, separate from this skill's git-tracked code.
• Multiple Claude sessions (including Task-tool sub-agents, which inherit the same filesystem and Python) can submit/list/wait concurrently — the daemon is a singleton (flock-guarded) and all writes go through short SQLite transactions in WAL mode.
• A hard daemon stop kills every currently-running job (recovered as failed, per the no-auto-retry policy — see above). This mostly matters when editing this skill's own scripts — the daemon doesn't hot-reload, so trying out a code change means stopping and letting the next command respawn it. Before doing that, always check list --status running first, and prefer daemon stop --graceful [--timeout SECS] over a plain stop — it stops accepting new job launches and waits (indefinitely by default) for whatever's already running to finish naturally, only then sending the actual stop signal; with `--timeo

…(truncated)