> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Automation

> What an automation is in Cosmos, how it wires an event source to an Expert, and where to inspect the events that fire one.

An **automation** is a persistent binding between an outside event and an Expert. Something happens out in the world — a PR opens, a Linear ticket changes state, a cron fires, a third-party service POSTs a webhook — Cosmos opens a session from the matching Expert and drops the raw event payload in as the first message. The Expert takes it from there.

If a Session is one conversation, an automation is the standing order that starts those conversations without you in the loop.

## How the Pieces Fit

Three things show up in every automation:

* **Expert** — the agent that runs. Its system prompt, capabilities, environment, and worker permissions decide what the session can do once it wakes up.
* **Trigger** — the binding that listens for an event and points it at the Expert. Triggers live inside an Expert's configuration; an Expert can have several.
* **Event** — the payload the trigger receives. Cosmos stores every event it sees so you can inspect what your filters are actually matching.

A trigger always has a **type**. The type is what kind of event source Cosmos is listening to:

| Trigger type | Fires on                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------ |
| GitHub       | Repository events from the connected GitHub App (PRs, pushes, comments, reviews).          |
| Linear       | Issue and comment events from the connected Linear app.                                    |
| Slack        | Mentions and messages from the connected Slack app.                                        |
| PagerDuty    | Incident events routed by a PagerDuty integration key.                                     |
| Scheduled    | A 5-field cron expression (see [Schedules](/cosmos/config-schedules)).                     |
| Webhook      | A POST to a tenant-scoped URL you mint yourself (see [Webhooks](/cosmos/config-webhooks)). |

Each trigger also takes an optional conditions that narrows the firing down to the subset of payloads you actually want. The filter runs against the raw event body before any session is created, so events you don't care about cost nothing.

## Webhooks Are a Trigger Type

Webhooks deserve a callout because they're the escape hatch. The first-party types (GitHub, Linear, Slack, PagerDuty) cover the systems Cosmos has a managed integration for. Anything else — GitLab, Jira, Datadog, CircleCI, a service you wrote yourself — talks to Cosmos through a **custom webhook**: an HTTPS endpoint you create from the Webhooks page, paste into the source system's outbound-webhook config, and reference from a `webhook`-typed trigger.

The same JSONLogic filter machinery works on a custom webhook's payload, so the receiving Expert only wakes up for the shapes you whitelist. Setup steps and the supported handler types (`bearer`, `gitlab`, `jira`, `github`) live in [Using Webhooks as Triggers](/cosmos/config-webhooks).

## Workers and Automations

Not every session in the events log was started by an automation. Some get launched as **workers** — sub-agents that a manager Expert spawns mid-session through `worker-launch`. A worker is its own session with its own messages and its own permissions, but it inherits the parent's environment and is bounded by the parent's `workerExpertIds` (or `useAllExpertsAsWorkers`) allowlist.

When you're tracing what happened in response to an event, this matters: the automation fires the parent session, and the parent decides whether to delegate to one or more worker sessions. The events log only records the inbound event; the worker tree is visible from the parent session's run history.

## Viewing Events

The **Events log** is where you watch automations actually fire. Open **Automations** in the sidebar, then click **Events** in the page actions — the URL is `/automations/events`.

The table shows every event Cosmos has received across all sources, with the most recent first. From here you can:

* Filter by **source** (GitHub, Linear, Slack, Custom, PagerDuty) using the source dropdown.
* Filter by **event type** (e.g. `pull_request`, `Issue`, `app_mention`) from the **Filter** dialog.
* Apply a **JSONLogic payload filter** in the same dialog and validate it against real captured events before pasting it into a trigger.
* Click any row to open the event details sheet, which shows the full headers and JSON payload that Cosmos received.

This is the same surface backend triggers see, so what passes your filter here is what will fire your automation in production.

### Per-Expert Run History

When you want to see what an individual Expert actually did in response to its events — not just what events arrived — open **Automations** in the sidebar and click the Expert's row to expand it, or follow the **Run history** link on that row. The URL is `/automations/run-history/:expertId`.

The run-history table is locked to a single Expert and lists every session that Expert produced, regardless of whether it was started by a human or by a trigger. Each row links into the session itself, where the worker tree (if any) is visible in the right sidebar.

## See Also

* [Using Webhooks as Triggers](/cosmos/config-webhooks) — the trigger reference, including custom webhook URLs and JSONLogic filters.
* [Using Schedules as Triggers](/cosmos/config-schedules) — cron syntax, timezones, and concurrency rules.
* [Your First Workflow Automation: End-to-End Tester](/cosmos/automation-tester) — a concrete automation, end to end.
* [Other Workflow Automations to Explore](/cosmos/automation-explore) — a few patterns people build first.