# Add a Periodic Task with Celery Beat

Yes. An agent adds a Celery beat schedule in the app's own settings style, runs Redis, a worker and beat in its sandbox, and shows the task firing on time.

[Run this on Rush](https://cloud.getrush.ai/run/add-periodic-tasks/celery/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

A periodic task is three things: a task, a schedule entry that names it, and a second process that sends it. The agent reads how the first is done before adding the other two. In an app like miguelgrinberg/flask-celery-example, everything is in `app.py`: `Celery(app.name, broker=app.config['CELERY_BROKER_URL'])`, then `celery.conf.update(app.config)`, and two tasks, `send_async_email` and `long_task`. `requirements.txt` pins `celery==4.4.1` with `redis==3.4.1`, the broker and result backend are both `redis://localhost:6379/0`, and the README starts one process besides Flask: `celery -A app.celery worker --loglevel=info`. Nothing runs beat, and the repository has no tests and no process file.

That configuration line shapes the change. The Flask config is copied into Celery whole, and `CELERY_RESULT_BACKEND` in it is one of Celery's old uppercase setting names. Celery 4 refuses a configuration that mixes old names with the new lowercase ones, so an agent that pastes a `beat_schedule` example from current documentation gets an `ImproperlyConfigured` error when the worker starts. The agent picks one style for the whole file and says which: either the schedule goes in as `CELERYBEAT_SCHEDULE` with `CELERY_TIMEZONE` beside the existing keys, or every Celery key moves to lowercase in the same commit. It sets the time zone explicitly either way, because a `crontab(hour=7, minute=0)` entry with no time zone means 07:00 UTC.

The task the issue asks for follows the pattern already in the file. `send_async_email` wraps `mail.send` in `with app.app_context()`, and the new task does the same for anything that touches Flask. It is declared with `ignore_result=True`, since nobody reads the return value of a job that fires on a timer, and it is written so that running twice does no harm. The schedule entry refers to the task by the name the worker registered. The agent reads that name from `celery -A app.celery inspect registered` and does not guess it from the module path. It adds the beat command to the README next to the worker's, and adds `celerybeat-schedule`, the file beat writes in its working directory, to `.gitignore`.

Then it runs all of it. The pins are from 2019 and 2020, so the agent first finds a Python version on which `pip install -r requirements.txt` succeeds and reports which one; it does not upgrade the pins as part of this job. It installs Redis with `sudo apt-get install -y redis-server`, since `run-redis.sh` in the repository builds Redis from source. With an environment variable that shortens the schedule to a few seconds, it starts the worker and `celery -A app.celery beat --loglevel=info` and keeps both logs: beat's line for each send and the worker's line for each task that succeeded. For mail it sets Flask-Mail's `MAIL_SUPPRESS_SEND`, so no message leaves the sandbox. It adds pytest tests that call the task body directly inside an app context and that load the schedule and check every entry names a registered task.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for a periodic task in this Flask and Celery app; the issue names the job and when it should run. Read requirements.txt, app.py, README.md, run-redis.sh and .gitignore first. Say in the pull request how Celery is configured today: where the app object is created, which setting-name style the configuration uses, the broker and result backend, and which processes the README starts. Add the task following the existing tasks: an app context around anything that uses Flask, ignore_result, and safe to run twice. Add the schedule in the same setting-name style as the rest of the configuration, or convert every Celery setting to lowercase in one commit; never mix the two styles. Set the time zone explicitly and say what it is. Refer to the task by the name shown by celery -A app.celery inspect registered. Let an environment variable override the interval for testing. Add the beat command to the README, say that exactly one beat process may run, and add celerybeat-schedule to .gitignore. Do not upgrade any pinned dependency; find a Python version the pins install on and report it. Install redis-server with apt, start Redis, a worker and beat with the interval set to a few seconds, let the task fire at least three times and paste the beat and worker log lines. Set MAIL_SUPPRESS_SEND so no email is sent. Add pytest tests for the task body and for the schedule naming only registered tasks. Open a pull request that links the issue.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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

The pull request changes `app.py`, `README.md` and `.gitignore` and adds tests. Its description states the schedule as a table: the task's registered name, the crontab or interval, the time zone, and the environment variable that overrides the interval. Under it are the logs from the sandbox: Redis starting, the worker's list of registered tasks, beat's send lines a few seconds apart, and the worker's matching success lines, followed by the pytest output and the Python version everything ran on.

It says how to deploy the change, because a schedule that is merged and never started looks the same as one that works. There is now a third process to run, `celery -A app.celery beat`, and exactly one copy of it: two beat processes each send every task, so every job runs twice. Workers can scale as before. The description also notes that beat keeps its last-run times in the `celerybeat-schedule` file, so the directory it runs in must be writable.

A reviewer checks the time zone against what the issue meant by "every morning", reads the task for anything that would be harmful if sent twice, and confirms the configuration uses one naming style throughout. If the agent converted the keys to lowercase, the diff to `app.py` is larger, and the worker log in the description is the proof that the old settings still took effect under their new names.

## Run it on every Linear issue labelled agent

Requests for scheduled jobs arrive one at a time: a nightly cleanup this week, a Monday report next month. With Linear connected under Settings → Connections in the console, add an automation to the Project with a `linear` trigger on `linear.issue.labeled` and the label `agent`. Its saved prompt asks for what this one asks for, without the specifics: read the issue, add the task and its schedule in the configuration's existing style, run a worker and beat, and open a pull request with the logs. The issue text arrives after the prompt, so the job's name and timing come from the issue itself.

The trigger fires only when someone in your Rush org adds the label, and a change made by an app integration never fires it. The run's pull request links the issue, so the person who asked sees the worker log before anyone merges.

## Why run it on Rush?

Whether a beat schedule works is not visible in a diff. The entry can name a task the worker never registered, sit under a key Celery ignores, or fire at an hour nobody intended, and the code still looks right. The only proof is a broker, a worker and beat running together long enough for the task to fire. The agent starts all three in its own sandbox, shortens the interval, and keeps the two logs side by side in the run's record, so the pull request shows sends and successes with timestamps.

Doing the same on a laptop means installing Redis, finding a Python old enough for 2019 pins, and keeping three terminals open while a timer counts down. That setup cost is why periodic tasks so often ship untested. The sandbox absorbs it, and several such issues can run at once without their Redis instances or schedule files touching each other.

## Frequently asked questions

### Does it work with Celery 5?

Yes. The agent reads the pinned version first. On Celery 5 the configuration is usually lowercase already, so the entry is `beat_schedule`, and the command is still `celery -A <app> beat`. What stays the same is the check that the settings use one naming style and that the task name comes from the worker's registry.

### Can I use the -B flag instead of a separate beat process?

For development, yes: `celery worker -B` embeds beat in one worker. In production it breaks as soon as a second worker starts with the same flag, because each embedded beat sends every task. The pull request documents the separate process for that reason.

### Will it upgrade my old Celery pins while it is there?

No. The prompt forbids it, and the agent reports the Python version the existing pins install on. An upgrade changes setting names and the command line at the same time, so it is safer as its own pull request with its own run.

### How do I know the schedule will fire at the right time and not just every few seconds?

The short interval comes from an environment variable that is unset in production, and the description prints the real schedule as loaded from the configuration, with its time zone. A test asserts that every schedule entry names a registered task, which is the mistake a fast interval would not catch.

## More Celery jobs

- [Add Prometheus Metrics to a Celery App](https://getrush.ai/run/add-prometheus-metrics/celery/)
- [Cancel a Running Celery Task](https://getrush.ai/run/add-task-cancellation/celery/)
- [Add Rate Limits to Celery Tasks](https://getrush.ai/run/add-task-rate-limits/celery/)

## The same job on other stacks

- [Add a Scheduled Job to a Flask App That Uses RQ](https://getrush.ai/run/add-periodic-tasks/rq/)

## More jobs like this: Turn a Linear label into a PR

- [Add Persistent Sessions to a grammY Telegram Bot With Redis](https://getrush.ai/run/add-persistent-sessions/grammy/)
- [Add Persistent User Settings to an Electron App from a Linear Issue](https://getrush.ai/run/add-persistent-settings/electron/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
