Skip to main content

Scheduled Triggers

Grackle can automatically create and start tasks on a schedule — cron jobs for your agents. Define a schedule with a cron expression or interval, link it to a persona and workspace, and Grackle handles the rest.

Creating a schedule​

From the CLI​

grackle schedule create "Nightly test suite" \
  --schedule "0 2 * * *" \
  --workspace <workspace-id> \
  --persona <persona-id> \
  --desc "Run the full test suite and post findings on any failures"

From the MCP server​

Agents can create schedules too — an orchestrator might set up recurring checks:

{
  "tool": "schedule_create",
  "input": {
    "title": "Dependency audit",
    "scheduleExpression": "1d",
    "workspaceId": "...",
    "personaId": "..."
  }
}

Schedule expressions​

Grackle supports two formats:

Interval shorthand​

Simple repeating intervals:

ExpressionMeaning
30sEvery 30 seconds
5mEvery 5 minutes
1hEvery hour
1dEvery day

Standard cron syntax​

Five-field cron expressions for precise scheduling:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

Examples:

ExpressionMeaning
0 2 * * *Daily at 2:00 AM
0 9 * * 1-5Weekdays at 9:00 AM
*/15 * * * *Every 15 minutes
0 0 1 * *First day of every month at midnight

How it works​

The scheduling plugin contributes a cron reconciliation phase that runs on every server tick:

  1. Check which schedules are due (based on nextRunAt)
  2. For each due schedule, create a task in the linked workspace
  3. Link the task to the schedule (for tracking)
  4. Enqueue the task for dispatch
  5. Advance the schedule (update lastRunAt, nextRunAt, runCount)

Tasks created by schedules go through the same lifecycle as any other task — they get dispatched to an available environment, run with the configured persona, and produce findings and results.

Managing schedules​

List schedules​

grackle schedule list
# Filter by workspace ID
grackle schedule list --workspace <workspace-id>

Enable or disable a schedule​

grackle schedule enable <schedule-id>
grackle schedule disable <schedule-id>

Delete a schedule​

grackle schedule delete <schedule-id>

Disabling the scheduling plugin​

If you don't need scheduled triggers, disable the plugin entirely:

GRACKLE_SKIP_SCHEDULING=1 grackle serve

This removes the cron phase and schedule gRPC handlers from the server.