Triggers

A trigger decides when an agent runs. Declare triggers in an agent config and Ellipsis registers them when the config syncs from your default branch. A config can declare more than one trigger, and the same agent can mix trigger types. There are three: cron runs on a schedule, react runs on a repository, issue, Linear, or Slack event, and mention answers @ellipsis where the work lives.

Cron

A cron trigger runs an agent on a schedule. Add a cron trigger to an agent config and Ellipsis registers the schedule when the config syncs from your default branch.

ellipsis:
  name: Daily triage
  description: Reviews new issues every weekday morning.
triggers:
  - type: cron
    schedule: "0 14 * * 1-5"
claude:
  system: |
    Find open GitHub issues that need attention.
    Prioritize bugs, stale customer reports, and blocked pull requests.
    Post a concise triage summary with owners and next actions.

Schedule format

schedule accepts a standard five-field cron expression: minute hour day-of-month month day-of-week. All schedules run in UTC.

You cannot restrict both day-of-month and day-of-week in the same expression. Leave one as *.

You can also pass an AWS EventBridge Scheduler expression directly with cron(...), rate(...), or at(...), and Ellipsis uses it as written.

triggers:
  - type: cron
    schedule: "rate(6 hours)"

Notes

• A cron agent has no typed prompt. The agent's system is the instruction it runs on each fire.
• A config can declare more than one cron trigger. Each schedule fires independently.
• Schedules are registered from the config on the default branch. Editing or removing the trigger updates or removes the schedule on the next sync.

Typical uses are daily triage, weekly summaries, and dependency checks.

React

A react trigger runs an agent when a repository, issue, Linear, or Slack workspace event happens. Declare the events you care about and Ellipsis starts a run each time a matching event lands. The agent acts on the event itself: there is no typed prompt, just the agent's system plus the event context.

Each entry under events names one event, and a config can list as many as it needs across any of the surfaces below.

ellipsis:
  name: Issue triager
triggers:
  - type: react
    events:
      - event: issue_open
claude:
  system: |
    A new issue was just opened. Read it, label it, and if it is a clear,
    small bug, open a draft pull request with a fix and link it back to the
    issue. Otherwise post a short triage comment with next steps.

Pull request events

Issue events

Push events

The push event also supports branches. Each entry is an exact branch name, a prefix ending in *, or default for the repository's default branch. An empty list matches every branch. Branch filters are only valid for push.

triggers:
  - type: react
    events:
      - event: push
        branches: ["release/*", "default"]
claude:
  system: |
    Code was just pushed. Run the smoke test suite. If anything fails, open
    an issue tagging the author of the head commit with the failing output.

A push to a branch with an open pull request can fire both push and pull_request_push for configs that declare them, so one webhook can start more than one run.

Linear events

Linear events require the Linear integration to be connected. They are workspace-wide and do not take a repository filter.

Slack channel events

The new channel's name, ID, creator, and creation time are passed to the agent as context. A Slack channel event has no repository of its own, so the run clones whatever repositories the agent config declares, the same as a cron run.

ellipsis:
  name: Channel welcomer
  description: Greets newly created Slack channels.
triggers:
  - type: react
    events:
      - event: slack_channel_created
claude:
  system: |
    A new Slack channel was just created. Post a short, friendly welcome
    message to the channel describing how the team usually uses channels
    like this one.

Limitations:

• Public channels only. slack_channel_created fires for public channels. Private-channel creation is a separate Slack event behind a different OAuth scope and is not supported.
• The event fires when a channel is first created, not when an existing channel is renamed or its visibility changes.

Repository filter

GitHub events (pull_request_*, issue_*, and push) accept a repository field to scope an event to a single repository. When omitted, the event applies to every repository on the config. Linear and Slack events are workspace-wide and ignore repository.

Mention

A mention trigger runs Ellipsis when someone mentions @ellipsis where the work already lives. Ellipsis starts a run with that conversation as context, answers in the thread, or makes code changes with the tools available to the run.

The mention agent's response is built in: it answers from the conversation it was mentioned in, so it has no system prompt. A mention config controls which platforms the agent answers on, plus the sandbox, model, and limits the run uses.

ellipsis:
  name: Mentions
  description: Answers @ellipsis on GitHub, Slack, and Linear.
triggers:
  - type: mention
    platforms: [github, slack, linear]

Platforms

platforms scopes where the agent answers. Leave it empty to answer on all of them.

Where mentions work

On GitHub, an @ellipsis mention is detected anywhere in the comment. On Linear, the comment must lead with @ellipsis so a mirrored GitHub thread does not summon Ellipsis again. In a Slack thread that already mentioned Ellipsis, a reply continues the run without mentioning it again.

What to ask

Use mentions for work that needs repository context or integration actions.

@ellipsis why does this migration need a backfill?

@ellipsis fix the connection leak from your review comment and open a PR