What the agent does
The agent reads the Worker's entry point and its bindings before adding a schedule. In a Worker shaped like the to-do-list-kv-template in cloudflare/templates, wrangler.jsonc names ./server.ts as main, sets compatibility_date 2025-10-08 with the nodejs_compat flag, turns observability on, uploads source maps, serves the Remix client build from ./build/client as assets, and binds one KV namespace as TO_DO_LIST. server.ts exports an object with a single fetch handler, typed with satisfies ExportedHandler
The data layer tells the agent what a scheduled job can usefully do. app/to-do-manager.ts is a TodoManager that stores one JSON array per list under a key chosen by the route, since app/routes/$id.tsx passes params.id as the key, and every put sets expirationTtl 300. The agent reads that and says so in the pull request: a nightly sweep of completed items only matters once a list outlives five minutes, so the handler is written to iterate every key with env.TO_DO_LIST.list and its cursor, drop completed todos older than a day from each array, and write the array back with the same TTL the manager uses, so the sweep never extends a list's life by accident. The handler lives in a new app/scheduled.ts so it can be unit tested without the Remix build.
Wiring it in is two edits. wrangler.jsonc gains a triggers block with one cron expression, and server.ts gains a scheduled method beside fetch that receives the controller, env and ctx and calls the sweep inside ctx.waitUntil, logging the cron string and the counts so Workers Logs, already enabled by the observability setting, shows each run. The check script, tsc followed by remix vite:build and wrangler deploy --dry-run, validates the config without deploying anything; the repository's own lint in cli/src/lint.ts only inspects compatibility_date, observability, upload_source_maps and the name matching package.json, so a triggers block passes it, and the agent runs pnpm -w check from the repository root to be sure.
Testing uses what the template already has. vitest.config.ts uses defineWorkersConfig from @cloudflare/vitest-pool-workers with the wrangler config path, and test/to-do-manager.test.ts imports env from cloudflare:test and clears the KV key after each case. The agent adds test/scheduled.test.ts in the same style: seed two lists through TodoManager, one with an old completed item and one with a fresh one, build a controller with createScheduledController, run the handler with createExecutionContext and waitOnExecutionContext, and assert on what is left in KV. For a manual check it runs wrangler dev with the test-scheduled flag and requests the __scheduled path with the cron string as a query parameter, and the output of that request goes in the description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a cron trigger to this Cloudflare Worker. Read wrangler.jsonc, package.json, server.ts, load-context.ts, worker-configuration.d.ts, app/to-do-manager.ts, app/routes/$id.tsx, vitest.config.ts and test/to-do-manager.test.ts first. Add a triggers block with one daily cron to wrangler.jsonc. Write the job in a new app/scheduled.ts: list every key in the TO_DO_LIST namespace with its cursor, remove completed todos older than one day from each list, and write each list back with the same expirationTtl the manager uses; note in the pull request that the TTL already expires idle lists after 300 seconds. Add a scheduled handler beside fetch in server.ts that runs the job inside ctx.waitUntil and logs the cron string and counts. Add test/scheduled.test.ts using createScheduledController, createExecutionContext and waitOnExecutionContext from cloudflare:test, seeding lists through TodoManager. Run npm run cf-typegen, npm run check, npm test and npm run lint in the template directory, run wrangler dev --test-scheduled and request /__scheduled with the cron as a query parameter, and open a pull request that quotes the test and dry-run output. Do not deploy.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch that edits wrangler.jsonc to add the triggers block, adds app/scheduled.ts and test/scheduled.test.ts, and extends server.ts with a scheduled method next to fetch. worker-configuration.d.ts is regenerated only if a binding changed, which this change does not require, and package.json is untouched because every tool it needs is already a dev dependency.
The description names the cron expression and what it does in words, quotes the vitest output and the wrangler deploy --dry-run result from the check script, and shows the local response to the __scheduled request with the cron string. It also records the TTL observation from app/to-do-manager.ts, so the reviewer knows the sweep is correct but mostly idle until the TTL changes.
Before merging, a reviewer checks that the handler writes lists back with the same expirationTtl and never without one, that the KV list loop follows the cursor until list_complete, that the cron runs in UTC at an hour that suits them, and that nothing was deployed: the transcript shows a dry run only. The deploy itself stays with the team's wrangler deploy or the Workers Builds integration.
Run it on every Worker without a schedule
Send this request once per Worker that needs a scheduled job, from a script that lists them and sets resources to each repository with a request_id per Worker, so a retried call returns the run already started. Each run gets its own sandbox, its own node_modules and its own local KV in the Vitest pool, so several Workers can be changed at once without sharing state.
Give the key a webhook URL and Rush POSTs run.completed with data.session_url when each turn finishes. When a reviewer wants the cron at another hour or a different retention window, a follow-up on the same session wakes the parked sandbox with the branch and the built client already there, and the agent edits, reruns the tests and pushes to the same pull request.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A scheduled handler is the kind of code nobody sees fail until it has run at three in the morning for a week. Proving it means a local run of the scheduled event, a Vitest pass against a real KV binding in the Workers pool, and a dry-run deploy to confirm wrangler accepts the config, all of which the agent does in its own sandbox with the template's own wrangler and vitest versions, leaving the output on the session.
The record is kept with the result. The transcript holds the files it read, the TTL it noticed, each command with its output and the __scheduled response, so a reviewer who did not watch can see that the job was exercised and not just typed. The Worker is not deployed by the run; the result is a pull request a person merges and ships.
Frequently asked questions
Will the agent deploy the Worker?
No. The check script runs wrangler deploy --dry-run, which validates the configuration without uploading anything, and the prompt forbids a real deploy. The cron starts firing only after your own deploy publishes the new wrangler.jsonc.
How is the scheduled handler tested without waiting for the cron?
Two ways. In Vitest, the Workers pool provides createScheduledController and createExecutionContext from cloudflare:test, so the handler runs against the local KV binding in a test. Locally, wrangler dev --test-scheduled exposes a __scheduled path that fires the handler on request with a cron query parameter.
Does the job change how lists expire?
No. The TodoManager writes every list with expirationTtl 300, and the sweep writes lists back with the same value, so it never extends a list's life. The pull request points out that with that TTL the nightly sweep rarely finds anything, and that raising the TTL is a separate decision.
Does this work for a Worker that is not built with Remix?
Yes. The scheduled handler sits on the same exported object as fetch in any Workers module, and the triggers block in wrangler.jsonc is the same. The agent reads your entry point from the main field and adds the handler there, with the job in its own module so it can be tested alone.
More Cloudflare Workers jobs
The same job on other stacks
More jobs like this: Hand off a long task
- Add CSRF Protection to an Actix Web App (Actix Web)
- Add CSRF Protection to an aiohttp App (aiohttp)