# Craft Agents Automation Events and Cron Schedule Configuration: Complete Guide

> Discover Craft Agents automation events for app lifecycle and agent activities. Learn to configure cron schedules with this complete guide.

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

---

**Craft Agents supports automation events defined in `APP_EVENTS` (application lifecycle) and `AGENT_EVENTS` (agent-specific activities), with cron schedules configured via the `time.cron` field in [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) using standard crontab syntax parsed by the scheduler service.**

Craft Agents enables event-driven workflows through its open-source automation system. The platform validates all automation events against canonical type definitions and executes time-based triggers using a built-in scheduler service. This guide covers the complete event taxonomy and cron configuration syntax based on the `craft-ai-agents/craft-agents-oss` repository source code.

## Supported Automation Events in Craft Agents

The runtime validates automation triggers against two authoritative constant arrays exported from [`packages/shared/src/automations/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/types.ts). These arrays are merged into the `VALID_EVENTS` list in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts), which rewrites deprecated aliases to canonical names at load time.

### Application Events (APP_EVENTS)

**Application events** track the lifecycle and state of the Craft Agents platform itself. Valid event names include:

- `AppStart`
- `AppClose`
- `AppFocus`
- `AppBlur`
- `AppInstall`
- `AppUpdate`
- `AppError`
- `AppLog`
- `AppCommand`
- `AppNotification`

These events fire when the application initializes, receives focus, encounters errors, or processes system-level commands.

### Agent Events (AGENT_EVENTS)

**Agent events** capture activities specific to individual AI agents and their sessions. The current implementation supports:

- `AgentInstalled`
- `AgentUpdated`
- `AgentRemoved`
- `SessionStatusChange`
- `TodoStateChange` (deprecated alias)
- `MessageReceived`
- `MessageSent`
- `PromptSubmitted`
- `PromptResponse`
- `ToolInvocation`
- `ToolResult`

According to the source code in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts), the `TodoStateChange` alias is automatically rewritten to `SessionStatusChange` during validation to maintain backward compatibility.

## How to Configure Cron Schedules in Craft Agents

Time-based automation relies on the `TimeConditionSchema` 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). The **scheduler service** located at [`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) parses standard cron expressions and registers timer jobs.

### Cron Configuration Syntax

Add a `time` condition containing a `cron` field to your automation definition:

```json
{
  "event": "AppStart",
  "conditions": {
    "time": {
      "cron": "0 9 * * 1-5"
    }
  },
  "actions": [
    {
      "type": "Prompt",
      "prompt": "Generate morning status report"
    }
  ]
}

```

The `cron` field accepts any valid Unix crontab string. The scheduler service validates the expression during the automation loading phase; malformed expressions cause the automation to be ignored with a warning emitted by the resource bundle loader in [`packages/shared/src/resources/resource-bundle.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/resources/resource-bundle.ts).

### Configuration Steps

1. **Create or edit** [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) at your workspace root.

2. **Define the time condition** using the `time.cron` field within a `conditions` object.

3. **Validate event names** against the `VALID_EVENTS` list—unknown events trigger warnings and are filtered out.

4. **Reload the configuration** by running `craft-agent automation reload` or restarting the Craft Agents process.

### Complete Example: Daily Automation

```json
{
  "version": 2,
  "automations": {
    "AppStart": [
      {
        "name": "DailySystemCheck",
        "event": "AppStart",
        "conditions": {
          "time": {
            "cron": "0 0 * * *"
          }
        },
        "actions": [
          {
            "type": "Prompt",
            "prompt": "Execute daily system health check"
          }
        ]
      }
    ]
  }
}

```

This configuration triggers the `AppStart` event daily at midnight, executing the specified prompt action through the scheduler service.

## Summary

- **Event definitions** live in [`packages/shared/src/automations/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/types.ts) as `APP_EVENTS` and `AGENT_EVENTS`, merged into `VALID_EVENTS` in [`schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/schemas.ts).
- **Cron schedules** use standard crontab syntax in the `time.cron` field of automation conditions.
- **Validation** occurs across [`schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/schemas.ts) (event names) and [`scheduler-service.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/scheduler-service.ts) (cron parsing).
- **Deployment** requires editing [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) and reloading via CLI or restart to activate schedules.

## Frequently Asked Questions

### What is the complete list of automation events supported by Craft Agents?

The complete list is defined in the `APP_EVENTS` and `AGENT_EVENTS` arrays within [`packages/shared/src/automations/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/types.ts). Application events cover lifecycle actions like `AppStart` and `AppClose`, while agent events include `SessionStatusChange`, `MessageReceived`, and `ToolInvocation`. The runtime merges these into `VALID_EVENTS` and filters out unknown event types during loading.

### How do I validate a cron expression in Craft Agents?

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) automatically validates cron expressions when loading [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json). Invalid expressions trigger warnings through the resource bundle loader, and the offending automation is ignored until the syntax is corrected to standard crontab format.

### Where do I configure automation schedules in the Craft Agents repository?

Configure schedules in the [`automations.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/automations.json) file at your workspace root using the `time.cron` field within a `conditions` object. The schema is 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) as `TimeConditionSchema`, and the scheduler service handles the timer registration.

### Can I use deprecated event names in my automation configuration?

Yes, deprecated aliases like `TodoStateChange` are automatically rewritten to their canonical names (`SessionStatusChange`) during validation in [`packages/shared/src/automations/schemas.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts). However, using canonical names is recommended for future compatibility as deprecated aliases may be removed in subsequent releases.