Skip to main content
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.
You can — and it’s strongly recommended to — ask Cosmos Advisor 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.

​
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. 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. Webhook — the escape hatch for anything without a managed integration (see below). See 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 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.

​
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

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 for the events log, per-Expert run history, and how to pause a trigger without deleting it.

​
See Also