Background Jobs & Scheduling

Superpowers can run automatically on a cron schedule. A morning briefing, a daily digest, a price alert — any action can be scheduled to run in the background and send results as a proactive message.

Declarative scheduling (recommended)

Add schedule to any action's triggers block. The job is created automatically when you deploy the superpower — no user message needed to set it up.

actions:
  - id: morning_job_scan
    description: Search for new job postings every morning
    triggers:
      schedule: "0 8 * * *"
      timezone: "America/Los_Angeles"
    operations:
      - type: web_search
        query: "software engineer jobs remote site:greenhouse.io"
        output: jobs

      - type: llm_generate
        prompt: "Summarize the top 3 most relevant jobs: {{$op.jobs}}"
        output: summary

      - type: notify
        message: "Morning job scan: {{$op.summary}}"
    response:
      template: "{{$op.summary}}"

When you deploy this superpower, the morning_job_scan action starts running automatically at 8 AM Pacific every day. No user interaction needed — the schedule is created at deploy time.

Schedule fields

Pausing a schedule

Set schedule_enabled: false to pause without removing the schedule. Re-deploy with true to resume.

triggers:
  schedule: "0 8 * * *"
  timezone: "America/Los_Angeles"
  schedule_enabled: false   # Paused — won't run until re-enabled

Hybrid triggers

An action can have both a schedule and keywords. It runs on the schedule automatically, AND responds when a user sends a matching message.

triggers:
  schedule: "0 9 * * 1"
  timezone: "America/New_York"
  keywords: [check prices, price update]

This checks prices every Monday at 9 AM ET, and also whenever the user asks.

Programmatic scheduling

For dynamic scheduling (where the user controls when to start), use the schedule operation inside an action:

actions:
  - id: setup_digest
    triggers:
      keywords: [set up digest, daily digest]
    operations:
      - type: schedule
        mode: recurring
        cron: "0 9 * * *"
        action_id: run_digest

  - id: run_digest
    triggers:
      keywords: []   # Only triggered by the schedule
    operations:
      - type: web_search
        query: "top tech news today"
        output: news

      - type: llm_generate
        prompt: "Summarize these headlines: {{$op.news}}"
        output: summary

      - type: notify
        message: "{{$op.summary}}"
    response:
      template: "{{$op.summary}}"

When the user says "set up a daily digest", the setup_digest action runs and creates a recurring job for run_digest. Use this approach when the schedule should be user-initiated rather than always-on.

Cron syntax

Standard 5-field cron expressions:

minute (0-59)
hour (0-23)
day of month (1-31)
month (1-12)
day of week (0-6, Sun=0)

*  *  *  *  *

Common patterns:

Notifications

Include a notify operation in scheduled actions. Without it, the action runs silently — the user gets no output.

operations:
  - type: web_search
    query: "..."
    output: results

  - type: notify
    message: "Here's what I found: {{$op.results}}"

When a scheduled job runs, the notification is sent as a proactive message through the user's companion (Luna, Nyx, etc.) via iMessage. The companion delivers it in character.

Notification rate limits:

• 3 notifications per superpower per user per day
• 5 total notifications per user per day

Tier limits

Free tier users can build and test superpowers with schedules, but the background jobs won't actually run until they upgrade.

Circuit breaker

If a job fails 3 times in a row, it's automatically paused with reason circuit_breaker. Fix the underlying issue, then re-deploy to resume.

Webhooks

For event-driven execution (external services calling your superpower), see webhook triggers. Webhooks are a separate mechanism — they use HMAC-SHA256 signed HTTP POST requests rather than cron schedules.