# Scheduled Tasks

CodeBuddy Code supports creating and managing scheduled tasks within a session. You can set up tasks that execute instructions on a recurring schedule or trigger a one-time action at a specific future time. Common use cases include: periodically checking build status, polling for task completion, setting reminders at specific times, and more.

> **Note**: Scheduled tasks are session-scoped. Tasks are only active while CodeBuddy Code is running and are automatically cleared upon exit.


## Creating One-Time Reminders

If you only need a reminder at a specific future time, you can describe it in natural language:

```
Remind me at 4:30 PM to sync today's progress
```

```
Check the build task output in one hour
```

```
Generate a daily work report for yesterday at 9 AM tomorrow
```

These tasks trigger once at the specified time and are automatically deleted after execution.

---

## Managing Existing Tasks

### View All Current Tasks

```
What scheduled tasks do I have right now?
```

The list includes the task ID, execution frequency, task type (recurring / one-time), and the associated instruction.

### Cancel a Task

```
Cancel the deployment check scheduled task
```

Or cancel by task ID:

```
Delete the scheduled task with ID xxx
```

Under the hood, these correspond to the `CronList` and `CronDelete` tools, which can be operated through conversation without needing to remember specific commands.

---

## Task Execution Mechanism

### Execution Timing

Tasks only trigger when the session is **idle** — that is, when the system is not processing other requests. If an operation is in progress when the task is due, the trigger is deferred until the operation completes.

### Time Jitter

The system adds a small random offset to task trigger times to prevent congestion from many tasks firing simultaneously:

- **Recurring tasks**: Delayed by up to 10% of the cycle duration (capped at 15 minutes)
- **One-time tasks**: For tasks set to the hour or half-hour, may trigger up to 90 seconds early

For example, a task set to run `every hour` may actually trigger randomly within 0–6 minutes after the hour.

### Auto-Expiration

**Recurring tasks automatically expire and are deleted after 3 days**, with one final trigger before expiration.
If you need tasks to persist longer, you can recreate them after expiration or use an external scheduling solution (such as GitHub Actions).

---

## Cron Expression Reference

For precise schedules like "every Monday at 10 AM" or "the 1st of every month," simply describe your requirement to the AI, and it will automatically convert it to a cron expression and create the task:

```
Generate a weekly work plan every Monday at 10 AM
```

```
On the 1st of every month, compile last month's code commit statistics grouped by contributor
```

```
Every Friday at 5:30 PM, remind me to sync progress and update task status
```

```
Every day at noon, check if there are any PRs awaiting my review
```

```
On weekdays at 9:15 AM, list yesterday's unmerged PRs
```

The AI response will include the actual cron expression and execution frequency used, so you can confirm whether it matches your expectations.

**Format:**
```
Minute  Hour  Day  Month  Weekday
```

**Common expressions:**

| Expression | Meaning |
|--------|------|
| `*/5 * * * *` | Every 5 minutes |
| `*/15 * * * *` | Every 15 minutes |
| `0 * * * *` | Every hour on the hour |
| `0 9 * * *` | Every day at 9 AM |
| `0 9 * * 1-5` | Weekdays at 9 AM |
| `0 0 1 * *` | Midnight on the 1st of every month |
| `30 18 * * 5` | Every Friday at 6:30 PM |

**Field descriptions:**

| Field | Range | Special Characters |
|------|---------|---------|
| Minute | 0–59 | `*` (any), `*/N` (every N minutes), `N,M` (list), `N-M` (range) |
| Hour | 0–23 | Same as above |
| Day | 1–31 | Same as above |
| Month | 1–12 | Same as above |
| Weekday | 0–6 | 0 or 7 = Sunday, 1 = Monday, and so on |

---

## Notes

| Item | Description |
|------|------|
| **Session-bound** | Tasks exist within the session. They are lost when CodeBuddy Code exits and are not persisted to disk |
| **Recurring task limit** | A maximum of 50 scheduled tasks can exist simultaneously per session |
| **Minimum interval** | 1 minute (sub-minute intervals are automatically rounded up) |
| **Task expiration** | Recurring tasks are automatically cleared after 3 days |
| **No backfill** | Missed tasks during session interruptions are not retroactively executed |

---

## Disabling Scheduled Tasks

To completely disable the scheduled tasks feature, set the following environment variable:

```bash
CODEBUDDY_DISABLE_CRON=1 codebuddy
```

Once enabled, the `/loop` skill is no longer available, and the `CronCreate`, `CronList`, and `CronDelete` tools are also disabled.

---

## Related Documentation

- [Skills System](./skills.md)
- [Slash Command Reference](./slash-commands.md)
- [Sessions and Context Management](./cli-reference.md)
- [Hooks Event System](./hooks.md)
