---
title: Scheduling and Recurring Runs
description: One-shot schedules, recurring parent issues, first-run controls, auto-stop behavior, time formats, and inspection commands.
relatedCommands:
  - alpaca issue create --help
  - alpaca issue show --help
  - alpaca issue list --help
  - alpaca service status --help
relatedDocs:
  - quick-start
  - issues
  - workflow-options
  - workflow-state
  - service-runtime
  - hierarchical-workflows
  - config
---

# Scheduling and Recurring Runs

Use this guide when a managed issue should run later, run repeatedly, or stop recurring after a defined condition.

## Choose a Schedule Type

| Need | Use | Result |
| --- | --- | --- |
| Run once at a known time | `--run-at <time>` | The issue waits as `AI: Scheduled`, then becomes runnable when due. |
| Run once after a delay | `--run-after <duration>` | The issue waits until the delay has elapsed. |
| Run repeatedly by fixed interval | `--every <duration>` | AlpacaLoop keeps a recurring parent issue and creates recurring child issues when due. |
| Run repeatedly on wall-clock times | `--cron "<5-field expr>"` | AlpacaLoop evaluates the cron expression in `i18n.displayTimeZone`. |
| Clear scheduling | `--schedule-off` | One-shot and recurring scheduling are removed from the workflow options. |

Put schedule options on `alpaca issue create` when creating the issue, or on the first non-empty line of a tracker comment with `/alpaca ...` when changing an existing issue. Do not put scheduled or recurring run instructions after that comment command; put them in the issue body because command body text is reserved for immediate same-issue replanning.

## One-Shot Schedules

One-shot schedules are for work that should run once in the future. Use them for delayed checks, planned follow-through, or work that should wait for an external date.

```bash
alpaca issue create --prompt "Check whether the release branch is ready." --run-at 2026-06-01T09:00:00+09:00
alpaca issue create --prompt "Re-check CI after the provider outage." --run-after 2h30m
```

`--run-at` accepts ISO-like future datetimes. Values with `Z` or an explicit `+HH:MM` or `-HH:MM` offset are unambiguous. Values without an offset use `i18n.displayTimeZone` from `alpaca.config.json`.

`--run-after` accepts compact positive durations with these units: `ms`, `s`, `m`, `h`, `d`, and `w`. Units can be combined, such as `2h30m` or `1w2d`.

## Recurring Runs

Recurring schedules keep the source issue open as a recurring parent. When the parent is due and below its active-child limit, the service creates a blocking recurring child issue to do the actual work. If the parent already has the maximum number of open recurring children, the due run is skipped and the parent advances to the next schedule.

Use `--every` for fixed intervals:

```bash
alpaca issue create --prompt "Refresh workflow templates from recent issue history." --every 30d --first-run-now
```

Use `--cron` for wall-clock schedules:

```bash
alpaca issue create --prompt "Run weekly release readiness checks." --cron "0 9 * * 1" --first-run-after 1h
```

`--every 1d` means a fixed 24-hour interval. It is not the same as "every day at 09:00." Use `--cron "0 9 * * *"` for wall-clock daily scheduling.

Cron expressions use five fields: minute, hour, day of month, month, and day of week. Supported field syntax includes `*`, exact values, ranges, comma lists, and step values such as `*/15`. Day of week uses `0` through `6`.

## First Run and Auto-Stop

Recurring issues can choose the first run separately from the recurring cadence:

| Need | Option |
| --- | --- |
| Start immediately | `--first-run-now` |
| Start at a known time | `--first-run-at <time>` |
| Start after a delay | `--first-run-after <duration>` |

Recurring issues can also stop automatically:

| Need | Option |
| --- | --- |
| Stop at a known time | `--stop-at <time>` |
| Stop after a time window | `--stop-after <duration>` |
| Stop after N child issues | `--stop-after-runs <count>` |
| Clear auto-stop | `--stop-off` |

When auto-stop becomes due, the parent waits for any open recurring children to close before the parent closes.

## Overlap and Child Titles

`recurring.maxActiveChildren` controls how many recurring children one parent can have open at the same time. The repository default is configured in `alpaca.config.json`, and one issue can override it with:

```bash
/alpaca --recurring-max-active-children 2
```

`recurring.updateChildTitleAfterPlan` controls whether a recurring child can update its title from the finalized plan. A recurring child run may force this on for that child while preserving the recurring prefix, run timestamp, and parent suffix.

## Inspect Scheduled Work

Use tracker labels for the quick state and `issue show` for the full workflow options:

```bash
alpaca issue list --days 14 --format markdown --limit 20
alpaca issue show --issue <id> --children 1 --limit 5 --format markdown
alpaca service status
alpaca service log show --tail 50
```

`AI: Scheduled` means a one-shot schedule or cooldown is waiting. `AI: Recurring` means AlpacaLoop is monitoring a recurring parent. Recent recurring child history is visible with `--children 1 --limit 5`; use `--children all --limit all` only when full history is required.

## Watch Outs

- Use `--run-at` or `--run-after` for one future run. Use `--every` or `--cron` only when repeated future runs are intended.
- Use explicit time offsets when a scheduled time must be unambiguous across machines.
- Keep the recurring parent open while monitoring or repeated work remains active.
- Recurring auto-stop settings are separate from AI run limits such as `--max-ai-runs` and `--max-ai-hours`.

## Related Docs

- `alpaca docs show issues`
- `alpaca docs show workflow-options`
- `alpaca docs show workflow-state`
- `alpaca docs show service-runtime`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show config`
