Automate actions when events occur — execute commands on schedules, react to label changes, or trigger prompts automatically

What It Does

Automations let you run actions in response to workspace events. When something happens — a label is added, a session status changes, a tool runs, or a cron schedule fires — automations execute shell commands or inject prompts into agent conversations automatically.

Configuration lives in automations.json at the workspace level:

path

~/.torlyai/workspaces/{workspaceId}/automations.json

Three Categories

Automations are organised by when they fire:

⏰ Scheduled

Fire on a cron schedule. Use for periodic tasks like daily briefings, backup triggers, or scheduled agent runs.

⚡ Event-based

React to app events like label changes, status updates, permission mode changes, and flag toggles.

🤖 Agentic

Hook into the agent lifecycle — before/after tool use, session start/end, prompt submission, and more.

How It Works

1Event fires

Something happens in your workspace

→

2Matcher checks

Regex or cron pattern is evaluated

→

3Action runs

Shell command or prompt executes

Event Types

App Events

Support both command and prompt actions:

Event	Description
`LabelAdd`	Fires when a label is added to a session.
`LabelRemove`	Fires when a label is removed from a session.
`LabelConfigChange`	Fires when label configuration is modified.
`PermissionModeChange`	Fires when the permission mode changes.
`FlagChange`	Fires when a session is flagged or unflagged.
`SessionStatusChange`	Fires when a session moves between statuses.
`SchedulerTick`	Fires every minute. Uses cron expressions for matching.

Agent Events

Support command actions only:

Event	Description
`PreToolUse`	Before a tool executes. Use to validate or gate tool calls.
`PostToolUse`	After a tool succeeds. Use to log or trigger side effects.
`PostToolUseFailure`	After a tool fails. Use for error handling or retry logic.
`UserPromptSubmit`	When the user submits a prompt.
`SessionStart`	When a session initiates.
`SessionEnd`	When a session concludes.
`Stop`	When the agent stops processing.
`SubagentStart`	When a subagent is spawned.
`SubagentStop`	When a subagent completes.

Action Types

Each automation can execute one of two action types:

Command Actions

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

{
  "type": "command",
  "command": "echo \"$TORLYAI_LABEL\" >> ~/log.txt",
  "timeout": 60000
}

Prompt Actions

Create a new agent session with a specified prompt. App events only. Supports @mentions for sources and skills.

{
  "type": "prompt",
  "prompt": "Review today's progress",
  "llmConnection": "my-connection",
  "model": "claude-sonnet-4-6"
}

Configuration

Automations are defined in automations.json using a version 2 schema. Each entry maps an event name to an array of matchers with actions:

automations.json

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

Matcher Options

Option	Default	Description
`matcher`	`(all)`	Regex pattern for filtering events
`cron`	`—`	Cron expression for SchedulerTick events
`timezone`	`system`	IANA timezone for cron (e.g. Europe/London)
`permissionMode`	`"safe"`	Security mode: "safe" or "allow-all"
`labels`	`[]`	Labels applied to prompt-created sessions
`enabled`	`true`	Boolean toggle to enable/disable
`actions`	`—`	Required array of actions to execute

Cron Scheduling

SchedulerTick events use standard cron expressions:

Format: minute · hour · day-of-month · month · day-of-week

*/15 * * * *Every 15 minutes

0 9 * * *Daily at 9:00 AM

0 9 * * 1-5Weekdays at 9:00 AM

30 14 1 * *1st of month at 2:30 PM

0 */6 * * *Every 6 hours

Environment Variables

Event data is passed to command actions as environment variables, prefixed with TORLYAI_:

Universal

TORLYAI_EVENTEvent name

TORLYAI_EVENT_DATAFull payload as JSON

TORLYAI_SESSION_IDCurrent session ID

TORLYAI_SESSION_NAMECurrent session name

TORLYAI_WORKSPACE_IDWorkspace ID

Label Events

TORLYAI_LABELLabel ID (LabelAdd / LabelRemove)

Status & Permission

TORLYAI_OLD_MODE / NEW_MODEPermission mode change

TORLYAI_IS_FLAGGEDFlag state ("true" or "false")

TORLYAI_OLD_STATE / NEW_STATEStatus transition

Scheduler

TORLYAI_LOCAL_TIMECurrent time (HH:MM)

TORLYAI_LOCAL_DATECurrent date (YYYY-MM-DD)

Tool Events

TORLYAI_TOOL_NAMETool being used

TORLYAI_TOOL_INPUTTool parameters as JSON

TORLYAI_TOOL_RESPONSETool output (PostToolUse only)

TORLYAI_ERRORError message (PostToolUseFailure)

Examples

Daily Weekday Briefing

Trigger a business plan review every weekday at 9 AM:

automations.json

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "Europe/London",
        "labels": ["Scheduled", "briefing"],
        "actions": [
          {
            "type": "prompt",
            "prompt": "Review today's business plan progress"
          }
        ]
      }
    ]
  }
}

Urgent Label Notification

Show a macOS notification when an urgent label is applied:

automations.json

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

Audit Trail

Log every tool execution to an audit file:

automations.json

{
  "version": 2,
  "automations": {
    "PostToolUse": [
      {
        "permissionMode": "allow-all",
        "actions": [
          {
            "type": "command",
            "command": "echo \"[$TORLYAI_LOCAL_TIME] $TORLYAI_TOOL_NAME\" >> ~/audit.log"
          }
        ]
      }
    ]
  }
}

Use Cases

Auto-assessment — trigger a 4F assessment whenever a business plan section status changes to “complete”
Quality gate — use a PreToolUse automation to require approval before agents modify business plan content
Notifications — run a shell command to send a Slack message when a task moves to Review
Scheduled reviews — use SchedulerTick to run daily consistency checks across your business plan
Audit trail — use PostToolUse automations to log all tool executions to a file

Managing in the UI

The Automations sidebar provides a visual interface for managing automations without editing JSON directly:

Enable / DisableToggle individual automations on and off

TestManually trigger an automation to verify it works

DuplicateClone an automation as a starting point

DeleteRemove automations you no longer need

HistoryView execution history for each automation

FilterBrowse by: Scheduled, Event-based, or Agentic

Rate Limiting & Security

Rate Limits

SchedulerTick: 60 fires/min
All other events: 10 fires/min
Excess events silently dropped

Security

Shell injection prevention via escaping
ReDoS protection (500-char limit)
Permission mode allowlist enforcement
Command timeouts with SIGKILL fallback

Migrating from Hooks? Automations replace the older Hooks system with the same version: 2 schema. If you have an existing hooks.json, rename it to automations.json — no content changes required. See Hooks (legacy) for the previous documentation.

Autopilot

Autonomous execution that automations can trigger

Config File

Global configuration reference

Automations

What It Does

Three Categories

How It Works

Event Types

App Events

Agent Events

Action Types

Command Actions

Prompt Actions

Configuration

Matcher Options

Cron Scheduling

Environment Variables

Universal

Label Events

Status & Permission

Scheduler

Tool Events

Examples

Daily Weekday Briefing

Urgent Label Notification

Audit Trail

Use Cases

Managing in the UI

Rate Limiting & Security

Rate Limits

Security

Related

Autopilot

Config File