> ## 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.

<Note>You can — and it's strongly recommended to — ask [Cosmos Advisor](/cosmos/advisor/overview) to set up automations for you by prompting rather than hand-editing triggers. Describe when an Expert should fire and the Advisor wires the right trigger and turns it on when you're ready, instead of you configuring triggers by hand.</Note>

## 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.

Every trigger has a **type** — the kind of event source Cosmos is listening to. The types fall into three groups:

**First-party integrations** — sources Cosmos has a managed integration for. Connect the integration once from the Integrations settings page — Cosmos owns the upstream registration — then any Expert can listen for its events.

| 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.                               |
| GitLab       | Push, merge request, and pipeline events from a connected GitLab project.         |
| PagerDuty    | Incident events routed by a PagerDuty integration key.                            |

**Scheduled** — no outside event at all; Cosmos is the event source. A `scheduled` trigger fires on a 5-field cron expression in the timezone you pick. See [Schedules](/cosmos/config-schedules).

**Webhook** — the escape hatch for anything without a managed integration (see below). See [Webhooks](/cosmos/config-webhooks).

Each trigger also takes an optional filter 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. The full reference — event types, filters, and how to add a trigger to an Expert — is on the [Configuring Triggers](/cosmos/config-triggers) page.

## Webhooks Are a Trigger Type

Webhooks deserve a callout because they're the escape hatch. The first-party types (GitHub, Linear, Slack, GitLab, PagerDuty) cover the systems Cosmos has a managed integration for. Anything else — Datadog, CircleCI, self-hosted GitLab, 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 common examples live in [Webhooks](/cosmos/config-webhooks).

## Subscriptions: Runtime Event Listeners

Triggers aren't the only way an event reaches an agent. A **subscription** is the runtime counterpart of a trigger: instead of being declared in an Expert's configuration by a human, it's created by an agent mid-session using its `subscribe-event` tool. When a matching event arrives, Cosmos doesn't open a new session — it delivers the event as a message into the session that created the subscription.

An agent typically creates subscriptions to:

* Watch a specific PR for comments, CI status changes, or a merge
* React to updates on a particular Linear ticket
* Listen for Slack mentions in a thread it's already working
* Poll on a schedule (cron-based health checks) without staying awake

Subscriptions support the same event sources and JSONLogic payload filters as triggers. Which sources an agent can subscribe to is gated by its Expert's capabilities (e.g. the GitHub capability unlocks GitHub subscriptions); scheduled subscriptions are always available. A subscription lives only as long as the session that created it — when the session ends, its subscriptions expire.

### Triggers vs. Subscriptions

| Aspect     | Triggers                               | Subscriptions                                |
| ---------- | -------------------------------------- | -------------------------------------------- |
| Created by | A human, in the Expert's configuration | The agent, at runtime via `subscribe-event`  |
| Lifetime   | Persistent                             | Scoped to the creating session               |
| On match   | Opens a new session from the Expert    | Delivers the event into the existing session |
| Use case   | "Start a reviewer whenever a PR opens" | "Tell me when *this* PR gets a comment"      |

When you're reading the events log, keep this distinction in mind: the same inbound event can fire a trigger (spawning a fresh session) and satisfy a subscription (waking an existing one).

## 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.

## Inspecting What Fired

The **events log** shows every event Cosmos has received across all sources, and **run history** shows what each Expert did in response. Both live under the **Automations** group in the sidebar. See [Managing Automations](/cosmos/manage-automations) for the events log, per-Expert run history, and how to pause a trigger without deleting it.

## See Also

* [Configuring Triggers](/cosmos/config-triggers) — the trigger reference: types, event names, and JSONLogic filters.
* [Webhooks](/cosmos/config-webhooks) — custom webhook URLs for everything else.
* [Managing Automations](/cosmos/manage-automations) — the events log, run history, and pausing a trigger.
* [Your First Automation](/cosmos/first-automation) — build two automations end to end.
* [Setting Up Automations with Advisor](/cosmos/automation-advisor) — describe the workflow and have Advisor wire it up for you.
* [Other Workflow Automations to Explore](/cosmos/automation-explore) — a few patterns people build first.