Skip to main content
Automations let you automate workflows by triggering actions when events happen — labels change, sessions start, tools run, or on a cron schedule.

​
Quick Start

Just ask the agent to set up an automation: 
"Set up a daily standup briefing every weekday at 9am"
The agent will create the automation configuration for you automatically.

​
Configuration File

Automations are defined in automations.json at the workspace level: 
~/.craft-agent/workspaces/{id}/automations.json

​
Basic Structure

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "labels": ["Automated"],
        "actions": [
          {
            "type": "prompt",
            "prompt": "An urgent label was added. Triage and summarise."
          }
        ]
      }
    ],
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "actions": [
          {
            "type": "prompt",
            "prompt": "Check @github for new issues assigned to me"
          }
        ]
      }
    ]
  }
}
The version field is optional. It’s reserved for future schema changes and currently defaults to version 2.

​
Automation Matchers

Each event type can have multiple matchers. A matcher defines:
FieldTypeDescription
idstring6-character hex ID (auto-generated)
namestringDisplay name (optional)
matcherstringRegex pattern for event data
cronstringCron expression (SchedulerTick only)
timezonestringIANA timezone (e.g., “Europe/Budapest”)
permissionModestringPermission mode: safe, ask, or allow-all
labelsstring[]Labels to apply to created sessions
enabledbooleanEnable/disable without removing (default: true)
actionsarrayList of actions to execute

​
Example Matcher

{
  "id": "a3f5c8",
  "name": "Track urgent issues",
  "matcher": "^urgent$",
  "permissionMode": "ask",
  "labels": ["Automated", "Urgent"],
  "enabled": true,
  "actions": [
    {
      "type": "prompt",
      "prompt": "Triage this urgent session: $CRAFT_SESSION_NAME"
    }
  ]
}

​
Prompt Actions

Prompt actions create new agent sessions with a specified prompt.

​
Basic Prompt

{
  "type": "prompt",
  "prompt": "Check for new issues and summarise"
}

​
Prompt with Source References

{
  "type": "prompt",
  "prompt": "Check @github for new issues assigned to me and notify @slack"
}
Use @sourceName to reference sources (like @github, @linear, @slack) and skills in your prompts.

​
Prompt with LLM Configuration

{
  "type": "prompt",
  "prompt": "Analyse security vulnerabilities in the latest commits",
  "llmConnection": "anthropic-primary",
  "model": "claude-opus-4"
}
FieldDescription
llmConnectionLLM connection slug (falls back to workspace default)
modelModel ID (falls back to provider default)

​
Environment Variables

Automation prompts support environment variables that are automatically expanded:

​
Core Variables

VariableDescription
$CRAFT_EVENTThe event type that triggered the automation
$CRAFT_SESSION_IDThe session ID (if available)
$CRAFT_SESSION_NAMEThe session name (sanitized for shell safety)
$CRAFT_WORKSPACE_IDThe workspace ID
$CRAFT_EVENT_DATAFull event payload as JSON

​
Event-Specific Variables

  • $CRAFT_LABEL - The label that was added or removed
  • $CRAFT_OLD_MODE - Previous permission mode
  • $CRAFT_NEW_MODE - New permission mode
  • $CRAFT_OLD_STATE - Previous status
  • $CRAFT_NEW_STATE - New status
  • $CRAFT_IS_FLAGGED - Whether session is flagged (true/false)
  • $CRAFT_LOCAL_TIME - Local time (HH:MM format)
  • $CRAFT_LOCAL_DATE - Local date (YYYY-MM-DD)

​
Example with Variables

{
  "type": "prompt",
  "prompt": "Session '$CRAFT_SESSION_NAME' was marked as $CRAFT_LABEL. Review and triage."
}

​
Permission Modes

You can set the permission mode for sessions created by automations: 
{
  "matcher": "^urgent$",
  "permissionMode": "allow-all",
  "actions": [
    {
      "type": "prompt",
      "prompt": "Automatically fix the urgent issue"
    }
  ]
}
ModeDisplayBehavior
safeExploreRead-only, blocks write operations
askAsk to EditPrompts for approval (default)
allow-allAutoAuto-approves all commands
Use allow-all with caution. It grants the agent full write access without prompts.

​
Labels

Automations can apply labels to sessions they create: 
{
  "cron": "0 9 * * 1-5",
  "labels": ["Scheduled", "Daily Standup"],
  "actions": [
    {
      "type": "prompt",
      "prompt": "Generate daily standup report"
    }
  ]
}
Labels support environment variable expansion: 
{
  "matcher": ".*",
  "labels": ["Auto-$CRAFT_LABEL"],
  "actions": [
    {
      "type": "prompt",
      "prompt": "Process labelled session"
    }
  ]
}

​
Enabling/Disabling Automations

Disable an automation without removing it: 
{
  "matcher": "^test$",
  "enabled": false,
  "actions": [
    {
      "type": "prompt",
      "prompt": "This won't run"
    }
  ]
}
Disabled automations remain in the configuration but won’t execute. Set enabled: true or remove the field to re-enable.

​
History Logging

All automation executions are logged to: 
~/.craft-agent/workspaces/{id}/automations-history.jsonl
Each line is a JSON object containing:
  • Event type
  • Timestamp
  • Matcher ID
  • Session ID
  • Labels applied
  • Execution result
The history is automatically rotated to keep the last 1000 entries.

​
Next Steps

Events Reference

Explore all supported events and their matchers

Automation Examples

Real-world automation recipes and patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us