Run a recurring task
6 minute read · Local Tasks
Give a recurring task a regular place in your day. Scheduled work uses your connected coding agent and a normal project chat on this computer.
- Create the first schedule
- Start the agent only when there is new work
- Understand timing and interruption
- Review and maintain scheduled work
- Choose work that can finish unattended
- Keep schedules separate from app processes
- Schedule fields and buttons
Create the first schedule
Open the project, select Scheduled in the sidebar and choose New scheduled task. Enter a recognizable name, a bounded prompt and the agent and model to use; the schedule belongs to the open project. Choose a daily time, such as 08:00, with an IANA timezone, or an elapsed interval. Start with Supervised access; automatic commit is off unless you deliberately opt in.
A suitable first task is: “Inspect this project's open local work and summarize the next useful step. Do not change files or contact external services.” Use Run now to verify the selected account, provider and project before depending on a future occurrence. The schedule reuses one ordinary chat so you can follow its earlier work.
Start the agent only when there is new work
Turn on Check for work before starting the agent to run a small script first. The agent starts only when the script prints new data. A schedule with a check shows Starts only when the check script returns new data., and Checking for work while the script runs.
- Add a script to the project, such as
scripts/check-work.py, that prints the items needing attention and nothing otherwise. - Enter its path in Check script, any Arguments (one per line) and a Check timeout in seconds from 1 to 300; the default is 30.
- Save, then use Run now to try it.
| Check result | What happens |
|---|---|
| No output | No data. The agent was not started. |
| The same output as the previous check | No new data. The agent was not started. |
| New output | The agent starts with that output attached as untrusted data. |
| Error, non-zero exit or timeout | The occurrence fails and the agent does not start. The schedule stays active. |
| Script changed since you saved the schedule | The occurrence is interrupted and the schedule pauses until you edit and save it again. |
Shell, JavaScript, Python and PHP scripts are supported, and PowerShell on Windows. The project must have a local folder. Up to 64 KiB of output is read and recognizable secrets are masked; still avoid printing credentials. The script runs on this computer with the project's environment, so keep it read-only and quick.
Understand timing and interruption
The desktop checks due work every 15 seconds and allows four automatic scheduled executions at a time, deferring others. Vortex must be open and the computer awake. Missed interval work produces one catch-up per task rather than replaying every missed occurrence. For daily schedules, a daylight-saving gap uses the next valid time and a repeated clock time runs once.
The occurrence is recorded durably before launch. Failed executions are not automatically retried. After a restart, a previously pending execution is marked interrupted and the schedule is paused for review. Review what the exact run already did before choosing Run now; some external actions may have completed before an interruption.
Review and maintain scheduled work
History points to the exact task/run and its result. Answer approvals in that run's conversation. Pause, edit or delete a schedule through its controls; those actions preserve the active chat. Configuration and the occurrence journal remain local and are not cloud-synchronized.
Signed-out, locked or mismatched-account states defer execution before launch. A synced chat does not create a hosted runner or cause a second device to execute the same schedule. Keep provider eligibility, resource access and explicit authorization current for any task that may write, send mail or publish.
Choose work that can finish unattended
Start with a read-only summary of the selected project's tests, recent changes or captured development errors. Include a clear stopping point and say which resources the task may use. A recurring prompt is an instruction to the connected agent, not an independent grant to modify a remote database, send a message or publish the app.
If a task needs approval, open the exact chat shown in its history and answer there. Leaving it unattended can leave the work waiting; a timer does not approve the action for you. Provider connection, account allowance and access to the selected local folder still need to be available at execution time.
Use Pause before changing a task you no longer want to run automatically. Inspect its latest run before resuming it. Deleting the schedule removes that recurring instruction while preserving the conversation and any work already performed.
Keep schedules separate from app processes
An application queue worker or development server is a process started with the project. A scheduled task starts an agent conversation occurrence. Keep the app's required services running through its project commands, then use the schedule for a bounded review or development task. Closing Vortex or letting the computer sleep prevents local scheduled work from running on time; there is no remote runner that takes over.
Related guides: approvals, project runtime, provider usage.
Schedule fields and buttons
| Control | Purpose |
|---|---|
| Scheduled tasks | Opens the local scheduler's saved definitions. |
| Name / instructions | Identifies the job and the prompt sent to its conversation. Keep the requested result bounded. |
| Agent | Selects the coding agent for the scheduled work. The schedule uses the open project's local checkout. |
| Model / Agent default | Uses an explicit supported model or the integration's default choice. Provider usage still applies. |
| Daily time / timezone | Defines a wall-clock schedule in the chosen timezone. Check daylight-saving behavior for that zone. |
| Interval | Repeats according to the configured elapsed interval rather than a daily clock time. |
| Enable / pause | Controls future scheduled execution. It is separate from stopping a run already in progress. |
| Run now | Triggers an eligible schedule immediately. With a check script, Run now still runs the check, and starts the agent even when the data has not changed since the last check. Disabled while conflicting work or required review prevents another run. |
| Check for work before starting the agent | Adds a check script that decides whether the agent starts. |
| Check script / Arguments (one per line) / Check timeout in seconds | The project-relative script, its arguments and its time limit. |
| Review approval | Opens the existing run's pending approval in its conversation. |
| Open conversation | Opens the schedule's reused chat. |
| History / Open run conversation | Shows previous run status/results and the associated evidence. |
| Delete schedule | Removes the schedule definition through its action. It is not a rollback of completed work. |
A schedule needs Vortex open, the computer awake, its checkout present and the provider usable. Failed work is not automatically retried; later occurrences still run. Interrupted work and changed check scripts pause the schedule for review. There is no remote runner. After changing a schedule, reopen it and verify its next-run information. See permissions and approvals.