Skip to main content

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.

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 typeFires on
GitHubRepository events from the connected GitHub App (PRs, pushes, comments, reviews).
LinearIssue and comment events from the connected Linear app.
SlackMentions and messages from the connected Slack app.
PagerDutyIncident events routed by a PagerDuty integration key.
ScheduledA 5-field cron expression (see Schedules).
WebhookA POST to a tenant-scoped URL you mint yourself (see 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.

​
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