Ikiro Developer Docs

Triggers determine when a superpower action runs. An action activates when any of its trigger conditions match.

Trigger types

keywords

Words that activate the action when present in the user's message. Case-insensitive, partial match.

triggers:
  keywords: [weather, forecast, temperature, umbrella]

"What's the weather like?" → matches "Is it going to rain?" → does NOT match (no keyword present)

phrases

Exact phrases (case-insensitive substring match).

triggers:
  phrases: [do I need an umbrella, should I bring an umbrella]

"Hey do I need an umbrella today?" → matches

has_image

Activate when the message contains an image.

triggers:
  has_image: true

Useful for receipt scanning, photo analysis, etc.

has_url

Activate when the message contains a URL.

triggers:
  has_url: true

state_condition

A template expression that must evaluate to true.

triggers:
  state_condition: "{{$state.items | length}} > 0"

Only matches if the session has items in state.

schedule

Run this action on a cron schedule — no user message needed. The action executes automatically at the specified time and sends results as a proactive notification.

triggers:
  schedule: "0 8 * * *"
  timezone: "America/Los_Angeles"

Runs every day at 8 AM Pacific. See Background Jobs for the full guide.

Related fields:

Field	Default	Description
`schedule`	—	Cron expression (e.g. `"0 8 * * *"`)
`timezone`	`"UTC"`	IANA timezone (e.g. `"America/Los_Angeles"`)
`schedule_enabled`	`true`	Set `false` to pause without removing

Common schedules:

Expression	Meaning
`0 8 * * *`	Every day at 8am
`0 9 * * 1`	Every Monday at 9am
`0 8,20 * * *`	Twice a day (8am + 8pm)
`0 /4 * *`	Every 4 hours
`30 8 * * 1-5`	Weekdays at 8:30am

Hybrid triggers: An action can have both a schedule and keywords — it will fire on the schedule AND when a user sends a matching message.

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

Important: Include a notify operation in scheduled actions, otherwise they run silently with no output to the user.

Top-level vs action triggers

There are two levels of triggers:

Top-level `trigger_patterns`

These control routing — whether the tool router even considers this superpower for a given message.

trigger_patterns:
  keywords: [weather, umbrella, rain]
  phrases: [do I need an umbrella]
  priority: 5

Action-level `triggers`

These determine which specific action within the superpower runs.

actions:
  - id: check_weather
    triggers:
      keywords: [weather, forecast]

  - id: check_umbrella
    triggers:
      keywords: [umbrella, rain]
      phrases: [do I need an umbrella]

If both actions could match, the first one with a matching trigger wins.

Priority

Top-level trigger_patterns.priority controls ordering when multiple superpowers could match. Range: 1-10 (default: 5). Higher priority = checked first.

trigger_patterns:
  keywords: [urgent]
  priority: 8  # Check before default-priority superpowers

Trigger Conditions