Automations

Just ask your agent. Say things like “create an automation that notifies me when a session is flagged” or “set up a daily morning briefing at 9am”. The agent will create and validate the configuration for you.

Automations let you trigger actions automatically when events happen in Craft Agent. You can run shell commands, send prompts to start new sessions, or schedule recurring workflows — all configured in a single JSON file.

Getting Started

The easiest way to set up automations is to describe what you want in plain language. Here are some prompts you can try:

What you want	What to say
Scheduled briefing	”Set up a daily standup briefing every weekday at 9am”
Desktop notifications	”Notify me with a macOS notification when a session is labelled urgent”
Audit logging	”Log all permission mode changes to a file”
Auto-label	”When a session starts, run a command that checks the working directory and logs it”
Recurring report	”Every Friday at 5pm, create a session that summarises this week’s completed tasks”
Webhook integration	”When I flag a session, send a curl request to my webhook URL”

Your First Automation

Here’s the simplest possible automation — it logs a message every time a label is added to a session:

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "actions": [
          { "type": "command", "command": "echo \"Label added: $CRAFT_LABEL\" >> ~/craft-automations.log" }
        ]
      }
    ]
  }
}

Save this as ~/.craft-agent/workspaces/{workspaceId}/automations.json and it starts working immediately — no restart needed.

Scheduling a Prompt

Want Craft Agent to do something for you on a schedule? Use a prompt action with a cron expression:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Check @github for any new issues assigned to me and summarise them" }
        ]
      }
    ]
  }
}

This creates a new session every weekday at 9 AM, activates the GitHub source, and asks the agent to check your issues. The session is automatically labelled “Scheduled” for easy filtering.

How Automations Work

When an event fires (e.g., a label is added, a tool runs, or a cron schedule matches), Craft Agent checks your configuration for matching entries and executes them. There are two types of actions:

Command actions — execute shell commands with event data available as environment variables
Prompt actions — send a prompt to Craft Agent, creating a new session (App events only)

Configuration File

Automations are configured per-workspace in automations.json:

~/.craft-agent/workspaces/{workspaceId}/automations.json

Basic Structure

{
  "version": 2,
  "automations": {
    "EventName": [
      {
        "matcher": "regex-pattern",
        "actions": [
          { "type": "command", "command": "echo 'Hello'" }
        ]
      }
    ]
  }
}

Each event type maps to an array of matchers, and each matcher contains an array of actions to execute when the matcher’s pattern matches the event value.

Managing Automations

In the UI

Automations are listed in the sidebar under Automations. From here you can:

Enable / Disable — Toggle individual automations on or off without removing them
Duplicate — Create a copy of an existing automation with a “Copy” suffix
Delete — Remove an automation permanently
Test — Manually trigger an automation to verify it works before waiting for the real event. The test runner resolves @mentions, enables sources, and uses the configured llmConnection/model — the same code path as the scheduler.
Execution history — Each automation records success and failure to a timeline, viewable in the detail page. History is stored in automations-history.jsonl and rotated to the last 1000 entries.

Batch operations are supported — select multiple automations and enable, disable, or delete them together. The list is sorted by most recent execution for quick access to active automations.

In the Config File

You can also manage automations by editing automations.json directly. Changes take effect immediately — no restart required. Enabling and disabling: Set "enabled": false on any matcher to temporarily disable it without removing the configuration. Omit the field or set it to true to re-enable.

{
  "matcher": "^urgent$",
  "enabled": false,
  "actions": [
    { "type": "command", "command": "notify-send 'Urgent!'" }
  ]
}

Deleting: Remove the matcher entry from automations.json. If an event type has no remaining matchers, you can remove the entire event key.

Ask your agent to manage automations for you: “disable all my scheduled automations” or “remove the urgent notification automation”. The agent will read and update automations.json directly.

Events

App Events

Triggered by Craft Agent itself. Support both command and prompt actions.

Event	Trigger	Match Value
`LabelAdd`	Label added to session	Label ID (e.g., `urgent`)
`LabelRemove`	Label removed from session	Label ID
`LabelConfigChange`	Label configuration changed	Always matches
`PermissionModeChange`	Permission mode changed	New mode name
`FlagChange`	Session flagged/unflagged	`true` or `false`
`SessionStatusChange`	Session status changed	New status (e.g., `done`)
`SchedulerTick`	Runs every minute	Uses cron matching

Renamed: TodoStateChange was renamed to SessionStatusChange. The old name still works as a deprecated alias but will show a validation warning. Update your automations to use SessionStatusChange.

Status changes: To react to status/workflow state changes (e.g., when a session moves to “done” or “in-progress”), use the SessionStatusChange event. The match value is the new status name, so you can use a matcher like "^done$" to trigger only on specific transitions.

Agent Events

Passed to the Claude SDK. Only command actions are supported (no prompt actions).

Event	Trigger	Match Value
`PreToolUse`	Before a tool executes	Tool name
`PostToolUse`	After a tool succeeds	Tool name
`PostToolUseFailure`	After a tool fails	Tool name
`UserPromptSubmit`	User submits a prompt	Event data JSON
`SessionStart`	Session starts	Event data JSON
`SessionEnd`	Session ends	Event data JSON
`Stop`	Agent stops	Event data JSON
`SubagentStart`	Subagent spawned	Event data JSON
`SubagentStop`	Subagent completes	Event data JSON
`Notification`	Notification received	Event data JSON
`PreCompact`	Before context compaction	Event data JSON
`PermissionRequest`	Permission requested	Event data JSON
`Setup`	Agent setup/initialization	Event data JSON

Action Types

Command Actions

Execute a shell command when the event fires. Event data is available through environment variables.

{
  "type": "command",
  "command": "echo \"Label $CRAFT_LABEL was added\" >> ~/automation-log.txt",
  "timeout": 60000
}

Property	Type	Default	Description
`type`	`"command"`	Required	Action type
`command`	string	Required	Shell command to execute
`timeout`	number	`60000`	Timeout in milliseconds

Prompt Actions

Send a prompt to Craft Agent, creating a new session. Only works with App events.

{
  "type": "prompt",
  "prompt": "Run the @weather skill and summarize today's forecast"
}

Property	Type	Default	Description
`type`	`"prompt"`	Required	Action type
`prompt`	string	Required	Prompt text to send
`llmConnection`	string	Workspace default	LLM connection slug (configured in AI Settings)
`model`	string	Workspace default	Model ID for the created session

Features:

Use @mentions to reference sources or skills (e.g., @github, @linear)
Environment variables are expanded (e.g., $CRAFT_LABEL, ${CRAFT_SESSION_NAME})
Mentioned sources are automatically activated for the new session

LLM Connection & Model: You can specify which AI provider and model to use for the session created by a prompt action. If omitted, the workspace default connection and model are used.

{
  "type": "prompt",
  "prompt": "Quick code review of recent changes",
  "llmConnection": "my-copilot-connection",
  "model": "gemini-3-pro-preview"
}

The llmConnection value is the slug of an LLM connection configured in AI Settings. The model value is a model ID supported by the provider. If either is invalid or not found, it gracefully falls back to the workspace default.

Matchers

Regex Matching

Most events use regex matching against the event’s match value:

{
  "matcher": "^urgent$",
  "actions": [
    { "type": "command", "command": "notify-send 'Urgent!'" }
  ]
}

Omit the matcher field to match all events of that type. Examples:

Pattern	Matches
`^urgent$`	Exact match for “urgent”
`bug\|feature`	Either “bug” or “feature”
`^prod-`	Any value starting with “prod-”
(omitted)	All events of that type

Cron Matching

For SchedulerTick events, use cron expressions instead of regex:

{
  "cron": "0 9 * * 1-5",
  "timezone": "Europe/Budapest",
  "actions": [
    { "type": "prompt", "prompt": "Give me a morning briefing" }
  ]
}

Cron format: minute hour day-of-month month day-of-week

Field	Range	Examples
Minute	0–59	`0`, `*/15`
Hour	0–23	`9`, `14`
Day of month	1–31	`1`, `15`
Month	1–12	`1`, `*/3`
Day of week	0–6 (0 = Sunday)	`1-5`, `0,6`

Common patterns:

Cron	Schedule
`/15 * * *`	Every 15 minutes
`0 9 * * *`	Daily at 9:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`30 14 1 * *`	1st of each month at 2:30 PM
`0 /6 * *`	Every 6 hours

Timezone: Uses IANA timezone names (e.g., Europe/Budapest, America/New_York). Defaults to system timezone if not specified. Verify with crontab.guru.

Matcher Options

Each matcher entry supports these optional fields:

Property	Type	Default	Description
`matcher`	string	Match all	Regex pattern for event filtering
`cron`	string	—	Cron expression (SchedulerTick only)
`timezone`	string	System TZ	IANA timezone for cron
`permissionMode`	string	`"safe"`	Security mode for commands
`labels`	string[]	`[]`	Labels applied to prompt-created sessions
`enabled`	boolean	`true`	Set to `false` to disable without deleting
`actions`	array	Required	Array of command/prompt actions

Environment Variables

Common Variables

Available to all command actions:

Variable	Description
`CRAFT_EVENT`	Event name (e.g., `LabelAdd`, `PreToolUse`)
`CRAFT_EVENT_DATA`	Full event payload as JSON
`CRAFT_SESSION_ID`	Current session ID
`CRAFT_SESSION_NAME`	Current session name
`CRAFT_WORKSPACE_ID`	Current workspace ID

App Event Variables

Dynamically generated from event payloads: Label events (LabelAdd, LabelRemove):

CRAFT_LABEL — Label ID being added/removed

PermissionModeChange:

CRAFT_OLD_MODE — Previous permission mode
CRAFT_NEW_MODE — New permission mode

FlagChange:

CRAFT_IS_FLAGGED — true or false

SessionStatusChange:

CRAFT_OLD_STATE — Previous session status
CRAFT_NEW_STATE — New session status

SchedulerTick:

CRAFT_LOCAL_TIME — Current time (HH:MM)
CRAFT_LOCAL_DATE — Current date (YYYY-MM-DD)

Agent Event Variables

Tool events (PreToolUse, PostToolUse, PostToolUseFailure):

CRAFT_TOOL_NAME — Tool being used
CRAFT_TOOL_INPUT — Tool parameters as JSON
CRAFT_TOOL_RESPONSE — Tool output (PostToolUse only)
CRAFT_ERROR — Error message (PostToolUseFailure only)

Session events (SessionStart):

CRAFT_SOURCE — Session source (e.g., startup, resume)
CRAFT_MODEL — Model name

Subagent events (SubagentStart, SubagentStop):

CRAFT_AGENT_ID — Subagent ID
CRAFT_AGENT_TYPE — Subagent type

Permission Modes

Command actions run with security checks by default. You can adjust this per matcher:

Mode	Behaviour	Use Case
`safe`	Commands checked against allowlist	Default, recommended
`allow-all`	Bypass security checks	Trusted automation only

Only use allow-all for commands you fully trust. It allows arbitrary shell execution.

{
  "matcher": "^urgent$",
  "permissionMode": "allow-all",
  "actions": [
    { "type": "command", "command": "osascript -e 'display notification \"Urgent!\" with title \"Craft Agent\"'" }
  ]
}

Labels for Prompt Actions

Prompt actions can attach labels to the sessions they create. This makes it easy to filter and organise scheduled sessions:

{
  "cron": "0 9 * * *",
  "labels": ["Scheduled", "morning-briefing"],
  "actions": [
    { "type": "prompt", "prompt": "Give me today's priorities" }
  ]
}

Labels also support environment variable expansion: "priority::${CRAFT_LABEL}".

Rate Limits

To prevent runaway loops (e.g., an automation that indirectly triggers itself), the event bus enforces rate limits:

Event	Max fires / minute
`SchedulerTick`	60 (1/sec)
All other events	10

Excess events are silently dropped for the remainder of the 60-second window.

Examples

Daily Morning Briefing

Schedule a prompt every weekday at 9 AM:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "Europe/Budapest",
        "labels": ["Scheduled", "briefing"],
        "actions": [
          { "type": "prompt", "prompt": "Run the @daily-standup skill" }
        ]
      }
    ]
  }
}

Log Label Changes

Track when labels are added or removed:

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "permissionMode": "allow-all",
        "actions": [
          { "type": "command", "command": "echo \"[$(date)] Added: $CRAFT_LABEL\" >> ~/label-log.txt" }
        ]
      }
    ],
    "LabelRemove": [
      {
        "permissionMode": "allow-all",
        "actions": [
          { "type": "command", "command": "echo \"[$(date)] Removed: $CRAFT_LABEL\" >> ~/label-log.txt" }
        ]
      }
    ]
  }
}

macOS Notification on Urgent Label

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "permissionMode": "allow-all",
        "actions": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Urgent session flagged\" with title \"Craft Agent\"'"
          }
        ]
      }
    ]
  }
}

Audit Permission Mode Changes

{
  "version": 2,
  "automations": {
    "PermissionModeChange": [
      {
        "permissionMode": "allow-all",
        "actions": [
          {
            "type": "command",
            "command": "echo \"$(date): $CRAFT_OLD_MODE -> $CRAFT_NEW_MODE\" >> ~/mode-audit.log"
          }
        ]
      }
    ]
  }
}

Multiple Schedules with Enable/Disable

Run different automations at different times, and disable some without deleting:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "Europe/Budapest",
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Give me a morning briefing" }
        ]
      },
      {
        "cron": "0 17 * * 5",
        "timezone": "Europe/Budapest",
        "enabled": false,
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Summarise this week's completed tasks" }
        ]
      }
    ]
  }
}

The second automation (Friday summary) is disabled and won’t run until "enabled" is set to true or removed.

Prompt with Specific LLM Connection

Use a different AI provider for a specific automation:

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 8 * * 1-5",
        "timezone": "Europe/Budapest",
        "labels": ["Scheduled"],
        "actions": [
          {
            "type": "prompt",
            "prompt": "Review overnight @github pull requests",
            "llmConnection": "openrouter",
            "model": "anthropic/claude-sonnet-4.5"
          }
        ]
      }
    ]
  }
}

Validation

Ask Craft Agent to validate your automations:

Validate my automations configuration

Or use the config_validate tool with target: "all". The validator checks for:

Invalid JSON syntax
Unknown event names
Empty actions arrays
Invalid cron expressions or timezones
Invalid or unsafe regex patterns (ReDoS prevention)
References to non-existent labels
Missing llmConnection slugs (error — will fail at runtime)
Model/provider mismatches when both llmConnection and model are specified (warning)

Security

Automations include several built-in safety measures:

Shell injection prevention — User-controlled values in environment variables (session names, labels, prompts) are automatically escaped
ReDoS protection — Regex patterns are limited to 500 characters and checked for catastrophic backtracking patterns
Rate limiting — Prevents infinite loops from automations that trigger other automations
Permission modes — Commands are checked against an allowlist by default
Timeouts — Commands are killed after their timeout expires (with SIGKILL fallback)

Best Practices

Start simple — Test with echo commands before writing complex scripts
Use labels — Tag scheduled sessions for easy filtering
Set timeouts — Prevent runaway commands with the timeout field
Log failures — Redirect stderr to track issues: command 2>> ~/automation-errors.log
Be specific — Use matchers to avoid triggering on every event
Test cron — Use crontab.guru to verify expressions
Use enabled: false — Temporarily disable automations instead of deleting them during debugging

Troubleshooting: Automation not firing

Check event name — Must be exact (e.g., LabelAdd not labeladd)
Check matcher — Regex must match the event’s match value
Check cron — For SchedulerTick, verify your cron expression
Check enabled — Ensure the matcher doesn’t have "enabled": false
Check logs — Look for [automations] in the application logs

Troubleshooting: Command blocked

If you see “Bash command blocked” errors:

Add "permissionMode": "allow-all" to the matcher
Or simplify the command to avoid shell constructs like $()

Troubleshooting: Prompt not creating session

Ensure the event is an App event (prompt actions don’t work with Agent events)
Check that the prompt text is not empty
Verify @mentions reference valid sources or skills

Getting Started

Core Concepts

Sources

Skills

Statuses

Labels

Customisation

Go Further

​Getting Started

​Your First Automation

​Scheduling a Prompt

​How Automations Work

​Configuration File

​Basic Structure

​Managing Automations

​In the UI

​In the Config File

​Events

​App Events

​Agent Events

​Action Types

​Command Actions

​Prompt Actions

​Matchers

​Regex Matching

​Cron Matching

​Matcher Options

​Environment Variables

​Common Variables

​App Event Variables

​Agent Event Variables

​Permission Modes

​Labels for Prompt Actions

​Rate Limits

​Examples

​Daily Morning Briefing

​Log Label Changes

​macOS Notification on Urgent Label

​Audit Permission Mode Changes

​Multiple Schedules with Enable/Disable

​Prompt with Specific LLM Connection

​Validation

​Security

Getting Started

Your First Automation

Scheduling a Prompt

How Automations Work

Configuration File

Basic Structure

Managing Automations

In the UI

In the Config File

Events

App Events

Agent Events

Action Types

Command Actions

Prompt Actions

Matchers

Regex Matching

Cron Matching

Matcher Options

Environment Variables

Common Variables

App Event Variables

Agent Event Variables

Permission Modes

Labels for Prompt Actions

Rate Limits

Examples

Daily Morning Briefing

Log Label Changes

macOS Notification on Urgent Label

Audit Permission Mode Changes

Multiple Schedules with Enable/Disable

Prompt with Specific LLM Connection

Validation

Security