Problem
You want Codex to run the same chore every weekday morning — sweep the repo for stale TODOs, draft a dependency-bump PR, summarize overnight CI failures — but you keep forgetting to kick it off. Or worse, you leave a chat tab open just to remember. Codex scheduled tasks fix that: you describe the job once, pick a cadence, and the cloud agent runs it on its own container without you in the loop.
This guide walks through setting up codex scheduled tasks in the Codex web app at chatgpt.com/codex, the same surface documented in OpenAI’s Codex changelog. It assumes you already have a Codex environment connected to a GitHub repo. If you don’t, start with our Codex workspace setup guide first.
Quick answer
In the Codex web app, open a task you’ve already run successfully, click the clock icon, and pick a recurrence (hourly, daily, weekly, or custom cron). Codex re-runs that exact prompt against a fresh clone of your repo on the schedule, posts results back to the task thread, and can open a PR if the prompt asks it to. You can run up to a few dozen scheduled tasks per account on Plus and Pro tiers, and each run consumes from your normal Codex usage limits.
NOTE
Scheduled tasks are a feature of the Codex cloud agent at chatgpt.com/codex, not the Codex CLI. The CLI runs locally and has no built-in scheduler — use cron or launchd for that.
Step-by-step workflow
1. Confirm your environment is connected
Open chatgpt.com/codex and check the Environments panel in the left sidebar. You need at least one GitHub repo connected with a working setup script — Codex spins up a fresh container for every scheduled run, so anything your task depends on (Node version, pnpm install, a .env template) must be reproducible from that script. If a manual run of any task fails because of missing dependencies, the scheduled version will fail the same way, silently, at 6am. Test the environment by running a throwaway task like “list the files in src/” and confirm it completes green.
IMPORTANT
If your repo requires secrets (API keys, DB URLs), add them as environment secrets on the Codex environment itself. Scheduled runs cannot prompt you for input mid-run.
2. Write the prompt as a standalone job
Create a new task in the Codex UI and write the prompt as if no human will ever read the output in real time. Bad: “check what’s broken.” Good: “Run pnpm test. If any tests fail, summarize the failures grouped by file in a markdown table and open a draft PR titled Nightly test triage — YYYY-MM-DD with the summary in the PR body. If all tests pass, post ‘all green’ to the thread and exit.” Be explicit about the success path, the failure path, and the artifact you want (PR, comment, file change). Scheduled tasks reward determinism — vague prompts produce drift you only notice a week later.
3. Run it manually once and verify
Click Run and watch the full execution end to end. Confirm the agent picks the right branch, the setup script completes, the prompt produces the artifact you expected, and the PR (if any) opens against the right base. This is the single most important step. Roughly half of failed codex scheduled tasks I’ve seen trace back to a prompt that worked once interactively (because the human nudged the agent mid-run) but breaks when run cold. If the manual run requires you to course-correct, edit the prompt and run it again until it completes with zero human input.
TIP
Save a copy of the working prompt in a prompts/ folder in your repo. When the schedule eventually breaks because your codebase moved on, you’ll want the diff history.
4. Attach a schedule
With a clean manual run in hand, click the clock/schedule icon on the task. Pick a cadence: every hour, daily at a specific UTC time, weekly on chosen days, or a custom cron expression like 0 14 * * 1-5 for weekdays at 14:00 UTC. Codex stores schedules in UTC — do the timezone math yourself or you’ll get a Monday-morning report at 3am local time. Name the schedule something you’ll recognize in the schedules list (e.g. “weekday-dep-audit”) because once you have five or six running, the default labels blur together.
5. Set up failure visibility
A scheduled task that silently fails for two weeks is worse than no task at all. Build a notification into the prompt itself: “At the end of the run, post the result (success or failure with reason) as a comment on issue #42 in this repo.” Codex doesn’t ping you on failed runs by default — the thread updates, but you have to go look. Pinning the output to a GitHub issue, a Slack webhook (via a curl in the prompt), or a tracked PR gives you a single place to glance at each morning. For high-stakes jobs like dependency updates, also require the agent to open a PR even on “nothing to do” so the absence of a PR signals breakage.
WARNING
Do not schedule tasks that can merge their own PRs, run terraform apply, or push to protected branches without review. A misfiring prompt at 3am with write access can cost you a weekend.
6. Layer in triggers if you need them
Schedules are time-based. If you actually want “run when a PR opens” or “run when CI fails on main,” you want triggers, not schedules. Codex supports both — see our companion guide on Codex automations and trigger-based workflows for the event-driven side. The two compose well: a nightly schedule for sweeps, plus an on-PR trigger for inline review.
Key concepts at a glance
| Concept | What it is | Practical analogy |
|---|---|---|
| Environment | The container template (repo + setup script + secrets) | A reusable VM image |
| Task | A saved prompt with a target environment | A shell script |
| Schedule | A cron-like cadence attached to a task | A crontab entry |
| Run | One execution of a scheduled task | A single cron invocation |
| Trigger | An event (PR opened, CI failed) that fires a task | A webhook |
Limits
Scheduled Codex tasks are useful but bounded. Things to know before you commit a workflow to them:
- Run-count caps. Free and Plus accounts get fewer concurrent schedules than Pro/Business. Heavy users hit the ceiling fast — a daily job across 10 repos is 10 schedules, not 1.
- No native fan-out. You can’t say “run this against every repo in my org.” One schedule = one task = one repo. Templating is manual.
- UTC only. Daylight saving will not adjust the schedule. Pick UTC times that work year-round.
- 15-minute granularity in practice. Even with custom cron, container cold-start adds variable latency. Don’t rely on minute-precise timing.
- No SLA. Scheduled runs can be delayed or skipped during platform incidents. Critical jobs (release cuts, billing) belong in your CI system, not Codex.
- Cost is per-run. Each scheduled execution counts against your normal Codex usage. A chatty hourly task can drain a month’s quota in days.
Alternatives
If codex scheduled tasks don’t fit — wrong cadence, missing event, need org-wide fan-out — these are the tools developers reach for instead.
| Tool | Integration model | Primary strength |
|---|---|---|
GitHub Actions (schedule: cron) | Native GitHub workflow | Free for public repos, full repo write access, fan-out via matrix |
| Claude Code + cron/launchd | Local CLI on your machine | No platform quota, full local filesystem access |
| Cursor background agents | IDE-integrated cloud agents | Tight loop with your editor sessions |
| Devin scheduled runs | Cognition’s autonomous agent | Long-horizon multi-step jobs |
| Zapier or n8n + OpenAI API | Workflow builder calling models directly | Cross-tool triggers (Slack, Linear, email) |
GitHub Actions is the honest competitor for most “nightly repo chore” use cases — you get cron syntax, secrets, fan-out, and audit logs for free, and you can call the OpenAI API from inside the action if you want a model in the loop. Pick Codex scheduled tasks when you want the agent’s planning and tool-use behavior; pick Actions when you want determinism and control.