Craft Agents Automation Events and Cron Schedule Configuration: Complete Guide

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 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. These arrays are merged into the VALID_EVENTS list in 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, 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. The scheduler service located at 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:

{
  "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.

Configuration Steps

1. Create or edit 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

{
  "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 as APP_EVENTS and AGENT_EVENTS, merged into VALID_EVENTS in schemas.ts.
• Cron schedules use standard crontab syntax in the time.cron field of automation conditions.
• Validation occurs across schemas.ts (event names) and scheduler-service.ts (cron parsing).
• Deployment requires editing 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. 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 automatically validates cron expressions when loading 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 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 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. However, using canonical names is recommended for future compatibility as deprecated aliases may be removed in subsequent releases.

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