Codex Native Scheduler

Schedule unattended Codex CLI jobs natively

Use the bundled scripts/codex-schedule CLI. It stores private state under $CODEX_HOME/codex-native-scheduler and registers only the native backend for the current platform.

Workflow

1. Run scripts/codex-schedule doctor before the first scheduled job on a host.

2. Confirm the intended working directory, schedule, and whether the prompt may write files.

3. Prefer --workspace worktree for write-capable recurring jobs. Direct jobs can conflict with other jobs using the same directory.

4. Use exactly one prompt source and exactly one schedule:

   console

   scripts/codex-schedule create \
     --name weekly-review \
     --cwd "$PWD" \
     --weekly-at mon@09:30 \
     --workspace worktree \
     --prompt-file ./weekly-review.md
   

5. Inspect the returned job and native status with status. Use run-now only when the user explicitly wants an immediate manual run.

6. Use runs and run-show for evidence. Raw JSONL, stderr, final output, and snapshots live in the reported run directory.

Configuration

Pass a Codex profile with --profile. Pass any Codex override repeatedly with -c key=value. Do not invent another permission acknowledgement or filter: Codex receives the values through codex exec --strict-config and enforces its own valid keys, authentication, approval, sandbox, and organization policies.

new_each_run is the default session mode. Use resume_fixed only when the task intentionally needs continuity; it forces overlap policy skip. Changing cwd or workspace mode for a fixed session requires update --reset-session. To continue an existing Codex session, create a direct resume_fixed job with --session-id SESSION_UUID; its --cwd should be the session's working directory. Seeded sessions do not inherit the scheduler's default profile and reject --profile and -c so the job cannot override the session's model settings. Profile and Codex overrides remain locked until update --reset-session starts a new session generation.

Operations

• pause JOB unregisters future wakes and leaves an active run alone.
• resume JOB registers future wakes again.
• stop RUN stops one active run.
• retry RUN creates a linked manual run and does not increment schedule count.
• prune [JOB] --dry-run previews retention cleanup.
• delete JOB --yes permanently deletes job state.
• decommission unregisters every job and preserves state before uninstalling.
• purge --yes removes state only after decommissioning.

Never enable Linux linger, edit Codex configuration, commit/merge/push a worktree, or delete a dirty worktree on the user's behalf.

Read references/semantics.md when exact count, catch-up, DST, retry, overlap, session, or retention behavior matters.