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

> Discover supported event-driven automations in Craft Agents. Learn how to configure triggers for app and agent events to execute custom actions and streamline your workflows.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```json
{
  "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:

```bash

# 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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/types.ts)
- **Zod schemas** in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) against Zod schemas defined in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.