Event-Driven Automations in Craft Agents: Supported Events and Configuration Guide

Craft Agents provides a built-in automation engine that watches App events (UI/workspace changes) and Agent events (SDK lifecycle hooks), executing configured actions like prompts and webhooks when pattern matchers or cron schedules fire.

The craft-ai-agents/craft-agents-oss repository ships with a comprehensive event-driven automation system implemented in TypeScript. This engine enables both developers and end users to define reactive workflows that respond to workspace state changes and agent lifecycle events through a declarative JSON configuration.

Automation Engine Architecture

The automation system is built on a layered architecture that ensures type safety and reliable execution.

Event Model and Type Definitions

At the core of the system, packages/shared/src/automations/types.ts defines the event taxonomy using two distinct groups:

• App events: Generated by the UI or workspace (e.g., label changes, permission updates)
• Agent events: Generated by the underlying Claude / Pi SDK (e.g., tool usage, session lifecycle)

These are combined into a union type AutomationEvent, with the canonical event names stored in the APP_EVENTS and AGENT_EVENTS constant arrays.

Schema Validation with Zod

Before any automation runs, the configuration undergoes strict validation. The file packages/shared/src/automations/schemas.ts contains Zod schemas including AutomationMatcherSchema, AutomationConditionSchema, and the top-level AutomationsConfigSchema. This layer filters unknown events and rewrites deprecated aliases to ensure backward compatibility.

Configuration Storage

Each workspace stores its automation rules in ~/.craft-agent/workspaces/<workspace-id>/automations.json. This file contains a JSON map where keys are event names and values are arrays of matcher objects defining conditions and actions.

Scheduler and Runtime Execution

The packages/shared/src/scheduler/scheduler-service.ts implements a cron-style scheduler that emits SchedulerTick events based on the cron field and optional timezone parameter in matchers. When events fire, packages/shared/src/automations/validation.ts handles the lookup, regex matching, condition evaluation, and action dispatching.

Supported Event Types

The engine recognizes specific canonical event names divided into two categories.

App Events (UI and Workspace)

Generated by user interactions and workspace state changes:

• LabelAdd – Fires when a label is applied to a session
• LabelRemove – Fires when a label is removed
• LabelConfigChange – Fires when label configuration updates
• PermissionModeChange – Fires when permission settings change
• FlagChange – Fires when feature flags toggle
• SessionStatusChange – Fires when session state transitions
• SchedulerTick – Fires based on cron schedule

Agent Events (SDK Lifecycle)

Exposed by the underlying agent SDK during operation:

• PreToolUse – Fires before tool execution
• PostToolUse – Fires after successful tool execution
• PostToolUseFailure – Fires when tool execution fails
• Notification – Fires on agent notifications
• UserPromptSubmit – Fires when user submits input
• SessionStart / SessionEnd – Session lifecycle events
• Stop – Agent stop signal
• SubagentStart / SubagentStop – Sub-agent operations
• PreCompact – Pre-compaction hook
• PermissionRequest – Permission request events
• Setup – Initialization event

Configuring Event-Driven Automations

The automations.json File

Create or edit ~/.craft-agent/workspaces/<workspace-id>/automations.json to define rules. The file uses a version 2 schema where each event maps to an array of matchers:

{
  "version": 2,
  "automations": {
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "actions": [
          { "type": "prompt", "prompt": "An urgent label was added. Triage the session and summarise next steps." }
        ]
      }
    ],
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Check @github for new issues assigned to me" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": ".*",
        "actions": [
          {
            "type": "webhook",
            "url": "https://example.com/webhook",
            "method": "POST",
            "headers": { "Content-Type": "application/json" },
            "body": { "tool": "{{tool_name}}", "session": "{{sessionId}}" },
            "captureResponse": true
          }
        ]
      }
    ]
  }
}

CLI Management

Interact with automations using the Craft CLI:

# List current automations

craft-cli automation list

# Create a scheduled automation

craft-cli automation create \
  --event SchedulerTick \
  --cron "0 8 * * *" \
  --action '{"type":"prompt","prompt":"Daily stand-up reminder"}'

Action Types

The engine currently supports two built-in actions extensible via the AutomationAction union type:

• prompt: Creates a new Craft session with the specified prompt text
• webhook: Issues an HTTP request with configurable method, headers, and body

Webhook actions support template variables like {{tool_name}} and {{sessionId}} that the engine expands before sending the request.

Execution Flow

When an event-driven automation triggers, the engine follows this sequence:

1. Event emission – The system emits an event (e.g., LabelAdd with payload { label: "urgent", sessionId: "abc" })
2. Matcher lookup – The engine reads automations.json and retrieves matchers for the specific event type
3. Pattern evaluation – The matcher regex (e.g., ^urgent$) tests against event payload values; cron expressions evaluate against current time
4. Condition checking – Optional conditions arrays filter based on time, state, or custom logic
5. Action execution – Validated matchers execute their actions array (prompts or webhooks)
6. Result handling – The engine returns an AutomationResult type containing any pending prompts for UI display

Summary

• Craft Agents supports event-driven automations through a JSON-based configuration system stored in ~/.craft-agent/workspaces/<id>/automations.json
• Two event categories exist: App events (UI/workspace) and Agent events (SDK lifecycle), with canonical names defined in types.ts
• Zod schemas in packages/shared/src/automations/schemas.ts validate configurations and maintain the VALID_EVENTS list
• Cron scheduling is supported via the SchedulerTick event and scheduler-service.ts
• Built-in actions include prompt (create sessions) and webhook (HTTP requests with template variables)
• The engine matches events using regex patterns, evaluates conditions, and executes actions atomically

Frequently Asked Questions

What file format does Craft Agents use for automation rules?

Craft Agents uses a JSON configuration file named automations.json located at ~/.craft-agent/workspaces/<workspace-id>/automations.json. The file follows a version 2 schema where top-level keys are event names (like LabelAdd or PreToolUse) and values are arrays of matcher objects containing matcher patterns, optional conditions, and actions arrays.

Can I schedule automations to run at specific times?

Yes. The SchedulerTick event supports cron expressions through the cron field in your matcher configuration. You can optionally specify a timezone parameter to ensure the schedule runs in the correct local time. The scheduler service in packages/shared/src/scheduler/scheduler-service.ts evaluates these expressions and emits the event when the schedule matches.

What variables are available in webhook actions?

Webhook actions support template placeholders that expand at runtime. Common variables include {{tool_name}}, {{sessionId}}, and other context-specific values from the triggering event. These placeholders are defined in the action's body or url fields and are replaced by the automation executor before the HTTP request is dispatched.

How does the engine validate automation configurations?

The engine validates automations.json against Zod schemas defined in packages/shared/src/automations/schemas.ts. This includes AutomationMatcherSchema for individual rules and AutomationsConfigSchema for the entire file. The validation layer filters unknown events, rewrites deprecated aliases, and ensures type safety before any automation is allowed to execute, preventing runtime errors from malformed configurations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}