Cue Event Types

Cue supports ten event types. Each type watches for a different kind of activity and produces a payload that can be injected into prompts via template variables.

app.startup

Fires exactly once when the Maestro application launches. Ideal for workspace setup, dependency installation, health checks, or any initialization that should happen once per session. Required fields: None beyond the universal name, event, and either prompt or prompt_file. Behavior:

Fires once per application launch
Does NOT re-fire when toggling Cue on/off in Settings
Does not re-fire on YAML hot-reload (deduplication by subscription name)
Resets on session removal (so re-adding the session fires again on next app launch)
Not affected by sleep/wake reconciliation
Works with fan_out, filter, output_prompt, and prompt_file

Example:

subscriptions:
  - name: init-workspace
    event: app.startup
    prompt: |
      Set up the development environment:
      1. Run `npm install` if node_modules is missing
      2. Check that required env vars are set
      3. Report any issues found

Payload fields:

Field	Type	Description
`reason`	string	Always `"system_startup"`

time.heartbeat

Fires on a periodic timer. The subscription triggers immediately when the engine starts, then repeats at the configured interval. Required fields:

Field	Type	Description
`interval_minutes`	number	Minutes between triggers (must be > 0)

Behavior:

Fires immediately on engine start (or when the subscription is first loaded)
Reconciles missed intervals after system sleep - if your machine sleeps through one or more intervals, Cue fires a catch-up event on wake
The interval resets after each trigger, not after each run completes

Example:

subscriptions:
  - name: hourly-summary
    event: time.heartbeat
    interval_minutes: 60
    prompt: |
      Generate a summary of git activity in the last hour.
      Run `git log --oneline --since="1 hour ago"` and organize by author.

Payload fields: None specific to this event type. Use common variables like {{CUE_TRIGGER_NAME}} and {{CUE_EVENT_TIMESTAMP}}.

time.scheduled

Fires at specific times and days of the week - a cron-like trigger for precise scheduling. Required fields:

Field	Type	Description
`schedule_times`	string[]	Array of times in `HH:MM` format (24-hour clock)

Optional fields:

Field	Type	Default	Description
`schedule_days`	string[]	every day	Days of the week to run: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`

Behavior:

Checks every 60 seconds if the current time matches any schedule_times entry
If schedule_days is set, the current day must also match
Does not fire immediately on engine start (unlike time.heartbeat)
Multiple times per day are supported - add multiple entries to schedule_times

Example - weekday standup:

subscriptions:
  - name: morning-standup
    event: time.scheduled
    schedule_times:
      - '09:00'
    schedule_days:
      - mon
      - tue
      - wed
      - thu
      - fri
    prompt: |
      Generate a standup report:
      1. Run `git log --oneline --since="yesterday"` to find recent changes
      2. Check for any failing tests
      3. Summarize what was accomplished and what's next

Example - multiple times daily:

subscriptions:
  - name: status-check
    event: time.scheduled
    schedule_times:
      - '09:00'
      - '13:00'
      - '17:00'
    prompt: |
      Run a quick health check on all services.

Payload fields:

Field	Description	Example
`matched_time`	The scheduled time that matched	`09:00`
`matched_day`	The day of the week when it triggered	`mon`

time.once

Fires exactly once at a specific wall-clock moment, then deletes itself from cue.yaml. This is the subsystem to reach for when a user says “in 20 minutes do X”, “tomorrow at 9am email me a summary”, “remind me at 4pm to push the rc branch”, or “schedule a 1h check-in” - anything that maps to a single action tied to a clock. Required fields:

Field	Type	Description
`fire_at`	string (ISO-8601)	The wall-clock moment to fire. Must include a timezone offset (`Z`, `±HH:MM`, or the colon-less `±HHMM`). Anything missing the offset is rejected at load time.

Optional fields:

Field	Type	Default	Description
`grace_minutes`	number	`360`	Missed-fire grace window in minutes. If Maestro is closed when `fire_at` arrives, the sub fires on next startup as long as the current time is within this window of `fire_at`. Past the window, the sub is logged as expired and self-destructs without firing.
`self_destruct_on_failure`	boolean	`true`	Whether to remove the sub from `cue.yaml` on a `failed` or `timeout` outcome. Set `false` to keep the sub in place for post-mortem inspection.

Behavior:

Poll-based at roughly 30-second granularity
Fires once when the wall clock crosses fire_at
Self-destructs from cue.yaml after a successful run (status completed)
On failed or timeout, also self-destructs unless self_destruct_on_failure: false
Supports all standard action values: prompt (default, runs the configured agent with the rendered prompt), notify (surfaces a toast through the owning agent - clicking it jumps there), and command (shell or CLI invocation)
The CLI command maestro-cli cue schedule is the supported way to create time.once subs - it handles ISO formatting, timezone offsets, target_node_key generation, and writes directly to the owning agent’s .maestro/cue.yaml. Do not hand-author time.once subscriptions.

Example - notify reminder:

subscriptions:
  - name: tasks-once-push-rc-reminder
    pipeline_name: Tasks
    event: time.once
    enabled: true
    fire_at: '2026-05-22T16:00:00-05:00'
    agent_id: <agent-uuid>
    action: notify
    notify:
      message: 'Push rc branch - review the diff first'
      sticky: true

Example - prompt run:

subscriptions:
  - name: tasks-once-20m-deploy-check
    pipeline_name: Tasks
    event: time.once
    enabled: true
    fire_at: '2026-05-22T14:20:00-05:00'
    agent_id: <agent-uuid>
    prompt: |
      Check the status of the deploy I kicked off and summarize the result.

Payload fields:

Variable	Description	Example
`{{CUE_FIRE_AT}}`	The originally-scheduled `fire_at` timestamp (ISO-8601)	`2026-05-22T16:00:00-05:00`

The standard {{CUE_TRIGGER_NAME}}, {{CUE_EVENT_TYPE}}, {{CUE_EVENT_TIMESTAMP}}, and {{CUE_PIPELINE_NAME}} variables are also available. Creating, listing, and cancelling:

# Schedule via relative offset
maestro-cli cue schedule --in 20m --agent <agent-id> --prompt "Check the deploy status."

# Schedule via absolute timestamp + notify-only
maestro-cli cue schedule --at "2026-05-22 16:00" --agent <agent-id> --notify --sticky --message "Push rc branch"

# List every pending one-time task across agents
maestro-cli cue schedule --list

# Cancel a pending task by sub name
maestro-cli cue schedule --cancel tasks-once-push-rc-reminder

file.changed

Fires when files matching a glob pattern are created, modified, or deleted. Required fields:

Field	Type	Description
`watch`	string (glob)	Glob pattern for files to monitor

Behavior:

Monitors for add, change, and unlink (delete) events
Debounces by 5 seconds per file - rapid saves to the same file produce a single event
The glob is evaluated relative to the project root
Standard glob syntax: * matches within a directory, ** matches across directories

Example:

subscriptions:
  - name: test-on-change
    event: file.changed
    watch: 'src/**/*.{ts,tsx}'
    filter:
      changeType: '!unlink' # Don't trigger on file deletions
    prompt: |
      The file {{CUE_FILE_PATH}} was {{CUE_EVENT_TYPE}}.
      Run the tests related to this file and report results.

Payload fields:

Variable	Description	Example
`{{CUE_FILE_PATH}}`	Absolute path to the changed file	`/project/src/app.ts`
`{{CUE_FILE_NAME}}`	Filename only	`app.ts`
`{{CUE_FILE_DIR}}`	Directory containing the file	`/project/src`
`{{CUE_FILE_EXT}}`	File extension (with dot)	`.ts`
`{{CUE_FILE_CHANGE_TYPE}}`	Change type	`add`, `change`, `unlink`

The changeType field is also available in filters.

agent.completed

Fires when another Maestro agent finishes a task. This is the foundation for agent chaining - building multi-step pipelines where one agent’s completion triggers the next. Required fields:

Field	Type	Description
`source_session`	string or list	Name(s) of the agent(s) to watch for completion

Behavior:

Single source (string): Fires immediately when the named agent completes
Multiple sources (list): Waits for all named agents to complete before firing (fan-in). See Fan-In
The source agent’s output is captured and available via {{CUE_SOURCE_OUTPUT}} (truncated to 5,000 characters)
Matches agent names as shown in the Left Bar

Example - single source:

subscriptions:
  - name: deploy-after-build
    event: agent.completed
    source_session: 'builder'
    filter:
      exitCode: 0 # Only deploy if build succeeded
    prompt: |
      The build agent completed successfully.
      Output: {{CUE_SOURCE_OUTPUT}}

      Deploy to staging with `npm run deploy:staging`.

Example - fan-in (multiple sources):

subscriptions:
  - name: integration-tests
    event: agent.completed
    source_session:
      - 'backend-build'
      - 'frontend-build'
    prompt: |
      Both builds completed. Run the full integration test suite.

Payload fields:

Variable	Description	Example
`{{CUE_SOURCE_SESSION}}`	Name of the completing agent(s)	`builder`
`{{CUE_SOURCE_OUTPUT}}`	Truncated stdout from the source (max 5K chars)	`Build succeeded`
`{{CUE_SOURCE_STATUS}}`	Run status (`completed`, `failed`, `timeout`)	`completed`
`{{CUE_SOURCE_EXIT_CODE}}`	Process exit code	`0`
`{{CUE_SOURCE_DURATION}}`	Run duration in milliseconds	`15000`
`{{CUE_SOURCE_TRIGGERED_BY}}`	Name of the subscription that triggered the source run	`lint-on-save`

These fields are also available in filters. The triggeredBy field is particularly useful when a source agent has multiple Cue subscriptions but you only want to chain from a specific one. See Selective Chaining for a complete example.

task.pending

Watches markdown files for unchecked task items (- [ ]) and fires when pending tasks are found. Required fields:

Field	Type	Description
`watch`	string (glob)	Glob pattern for markdown files to scan

Optional fields:

Field	Type	Default	Description
`poll_minutes`	number	1	Minutes between scans (minimum 1)

Behavior:

Scans files matching the glob pattern at the configured interval
Fires when unchecked tasks (- [ ]) are found
Only fires when the task list changes (new tasks appear or existing ones are modified)
The full task list is formatted and available via {{CUE_TASK_LIST}}
File content (truncated to 10K characters) is available via {{CUE_TASK_CONTENT}}

Example:

subscriptions:
  - name: todo-worker
    event: task.pending
    watch: '**/*.md'
    poll_minutes: 5
    prompt: |
      Found {{CUE_TASK_COUNT}} pending tasks in {{CUE_TASK_FILE}}:

      {{CUE_TASK_LIST}}

      Pick the most important task and complete it.
      When finished, mark it as done by changing `- [ ]` to `- [x]`.

Payload fields:

Variable	Description	Example
`{{CUE_TASK_FILE}}`	Path to the file containing tasks	`/project/TODO.md`
`{{CUE_TASK_FILE_NAME}}`	Filename only	`TODO.md`
`{{CUE_TASK_FILE_DIR}}`	Directory containing the file	`/project`
`{{CUE_TASK_COUNT}}`	Number of pending tasks found	`3`
`{{CUE_TASK_LIST}}`	Formatted list with line numbers	`L5: Write unit tests`
`{{CUE_TASK_CONTENT}}`	Full file content (truncated to 10K chars)	(file contents)

github.pull_request

Polls GitHub for new pull requests using the GitHub CLI (gh). Optional fields:

Field	Type	Default	Description
`repo`	string	auto	GitHub repo in `owner/repo` format. Auto-detected from git remote if omitted
`poll_minutes`	number	5	Minutes between polls (minimum 1)

Behavior:

Requires the GitHub CLI (gh) to be installed and authenticated
On first run, seeds the “seen” list with existing PRs - only new PRs trigger events
Tracks seen PRs in a local database with 30-day retention
Auto-detects the repository from the git remote if repo is not specified

Example:

subscriptions:
  - name: pr-reviewer
    event: github.pull_request
    poll_minutes: 3
    filter:
      draft: false # Skip draft PRs
      base_branch: main # Only PRs targeting main
    prompt: |
      New PR: {{CUE_GH_TITLE}} (#{{CUE_GH_NUMBER}})
      Author: {{CUE_GH_AUTHOR}}
      Branch: {{CUE_GH_BRANCH}} -> {{CUE_GH_BASE_BRANCH}}
      Labels: {{CUE_GH_LABELS}}
      URL: {{CUE_GH_URL}}

      {{CUE_GH_BODY}}

      Review this PR for:
      1. Code quality and style consistency
      2. Potential bugs or edge cases
      3. Test coverage

Payload fields:

Variable	Description	Example
`{{CUE_GH_TYPE}}`	Always `pull_request`	`pull_request`
`{{CUE_GH_NUMBER}}`	PR number	`42`
`{{CUE_GH_TITLE}}`	PR title	`Add user authentication`
`{{CUE_GH_AUTHOR}}`	Author’s GitHub login	`octocat`
`{{CUE_GH_URL}}`	HTML URL to the PR	`https://github.com/org/repo/pull/42`
`{{CUE_GH_BODY}}`	PR description (truncated)	(PR body text)
`{{CUE_GH_LABELS}}`	Comma-separated label names	`bug, priority-high`
`{{CUE_GH_STATE}}`	PR state	`open`
`{{CUE_GH_BRANCH}}`	Head (source) branch	`feature/auth`
`{{CUE_GH_BASE_BRANCH}}`	Base (target) branch	`main`
`{{CUE_GH_REPO}}`	Repository in `owner/repo` format	`RunMaestro/Maestro`

github.issue

Polls GitHub for new issues using the GitHub CLI (gh). Behaves identically to github.pull_request but for issues. Optional fields:

Field	Type	Default	Description
`repo`	string	auto	GitHub repo in `owner/repo` format
`poll_minutes`	number	5	Minutes between polls (minimum 1)

Behavior: Same as github.pull_request - requires GitHub CLI, seeds on first run, tracks seen issues. Example:

subscriptions:
  - name: issue-triage
    event: github.issue
    poll_minutes: 5
    filter:
      labels: '!wontfix' # Skip issues labeled wontfix
    prompt: |
      New issue: {{CUE_GH_TITLE}} (#{{CUE_GH_NUMBER}})
      Author: {{CUE_GH_AUTHOR}}
      Assignees: {{CUE_GH_ASSIGNEES}}
      Labels: {{CUE_GH_LABELS}}

      {{CUE_GH_BODY}}

      Triage this issue:
      1. Identify the area of the codebase affected
      2. Estimate complexity (small/medium/large)
      3. Suggest which team member should handle it

Payload fields: Same as github.pull_request, except:

Variable	Description	Example
`{{CUE_GH_TYPE}}`	Always `issue`	`issue`
`{{CUE_GH_ASSIGNEES}}`	Comma-separated assignee logins	`alice, bob`

The branch-specific variables ({{CUE_GH_BRANCH}}, {{CUE_GH_BASE_BRANCH}}) are not available for issues.

cli.trigger

Fires only when explicitly triggered from the command line via maestro-cli cue trigger <name>. Unlike other event types, cli.trigger has no background watcher or poller - it waits for a manual invocation. No additional fields required - just name, event, prompt, and optionally enabled. Behavior:

Does nothing on its own - only fires when you run maestro-cli cue trigger <subscription-name>
Supports an optional --prompt flag to override or supply the prompt at invocation time
The override text is available in the prompt template as {{CUE_CLI_PROMPT}}
Ideal for deployment scripts, CI/CD integration, on-demand reviews, or ad-hoc automation

Example:

subscriptions:
  - name: deploy
    event: cli.trigger
    prompt: |
      Run the deployment pipeline for the current branch.

      Additional instructions: {{CUE_CLI_PROMPT}}
    enabled: true

Triggering from the command line:

# Basic trigger - uses the configured prompt as-is
maestro-cli cue trigger deploy

# With a prompt override - {{CUE_CLI_PROMPT}} receives this text
maestro-cli cue trigger deploy --prompt "Deploy to staging only"

# JSON output for scripting
maestro-cli cue trigger deploy --json

Discovering available subscriptions:

# List all subscriptions across agents
maestro-cli cue list

Payload fields:

Variable	Description	Example
`{{CUE_CLI_PROMPT}}`	Prompt text passed via `--prompt` flag	`Deploy to staging`
`{{CUE_TRIGGER_NAME}}`	Name of the subscription that was triggered	`deploy`
`{{CUE_EVENT_TYPE}}`	Always `cli.trigger`	`cli.trigger`

​app.startup

​time.heartbeat

​time.scheduled

​time.once

​file.changed

​agent.completed

​task.pending

​github.pull_request

​github.issue

​cli.trigger

app.startup

time.heartbeat

time.scheduled

time.once

file.changed

agent.completed

task.pending

github.pull_request

github.issue

cli.trigger