Skip to content

Schedules

Schedules let you automate recurring tasks by running agent teams on a cron-based cadence. Define a prompt, pick a team, set the frequency, and AgentCrew handles the rest: deploying the team, sending the prompt, recording the result, and tearing down the infrastructure.

How Schedules Work

When a schedule fires, AgentCrew performs the following steps automatically:

  1. Deploy the assigned team (containers, NATS bus, workspace).
  2. Send the configured prompt to the team leader via NATS.
  3. Wait for the leader's response (up to the configured timeout).
  4. Record the prompt and response as a schedule run.
  5. Tear down the team infrastructure to free resources.

The entire lifecycle is managed by a background scheduler engine that ticks every 60 seconds, evaluates cron expressions, and launches executions in parallel with configurable concurrency limits. When multiple schedules target the same team, messages are queued and processed sequentially (FIFO) — see Task Processing Model for details.

Creating a Schedule

Navigate to the Schedules section in the sidebar and click New Schedule. The schedule builder walks you through:

  1. Name: A descriptive name for the schedule (e.g., "Weekly Blog Post", "Daily Report").
  2. Team: Select which agent team will execute the task. The team must already exist.
  3. Prompt: The instruction sent to the team leader when the schedule fires. Write it as you would in the chat interface.
  4. Frequency: Use the visual builder to pick hourly, daily, weekly, or monthly cadences. The builder generates the cron expression for you.
  5. Timezone: Schedules evaluate cron expressions in the selected timezone. Your browser timezone is auto-detected, but you can change it.

Frequency Builder

The visual frequency builder simplifies cron expression creation. You don't need to know cron syntax — just pick the pattern:

Frequency Options Example cron
Hourly Runs once per hour at a fixed minute 0 * * * *
Daily Runs once per day at a specific time 30 9 * * *
Weekly Pick one or more days of the week and a time 0 10 * * 1,3,5
Monthly Pick a day of the month and a time 0 8 1 * *

The generated cron expression is displayed as a live preview in human-readable format (e.g., "Every Monday, Wednesday, Friday at 10:00").

Managing Schedules

Enable / Disable

Each schedule has a toggle to enable or disable it. Disabled schedules are not evaluated by the scheduler engine. When re-enabled, the next run time is recalculated automatically.

Editing

Click any schedule to edit its name, prompt, team, frequency, or timezone. Changes take effect immediately — the next run time is recalculated on save.

Deleting

Deleting a schedule removes it and all its run history permanently.

Run History

Each schedule maintains a paginated history of all executions. For every run you can see:

  • Status: success, error, or timeout.
  • Started at / Finished at: Timestamps in your local timezone.
  • Duration: How long the execution took.
  • Conversation: Expand any run to see the full prompt sent and the agent's response, rendered as a mini-chat with Markdown support.

You can also navigate directly to the team's chat from any schedule detail page using the chat icon in the header.

Configuration

The scheduler engine behavior can be tuned with environment variables:

Variable Default Description
SCHEDULE_TIMEOUT 1h Maximum time to wait for a team response before marking the run as timed out. Accepts Go duration strings (e.g., 30m, 2h).
SCHEDULER_MAX_CONCURRENT 10 Maximum number of schedules that can execute simultaneously. Excess schedules are deferred to the next tick.

Architecture Notes

  • The scheduler runs as a background goroutine inside the API server process — no separate service is needed.
  • Schedule claims are atomic: the engine uses a database-level compare-and-swap (UPDATE WHERE status = 'idle') to prevent double-firing when ticks overlap.
  • Executions are isolated: each run deploys a fresh team instance and tears it down after completion, ensuring no state leaks between runs.
  • Panic recovery ensures that a failing execution never crashes the scheduler — the schedule is reset to idle and the error is logged.
  • Per-team FIFO processing: Each team runs a single Claude Code process. When multiple schedules target the same team, messages are queued and processed one at a time in arrival order. A correlation ID ensures each executor receives the correct response, even when schedules overlap.

Next Steps

  • Configuration: Review all environment variables including scheduler-specific settings.
  • Architecture: Understand how the scheduler fits into the overall system design.