Automations

An automation is a saved agent that runs on a trigger or when invoked. Define it as YAML under agents/ in your repository, or through the API.

An automation is a saved agent: a trigger, a persona, and the environment it runs in. A session is you working with an agent; an automation is an agent working without you, on a schedule, on a repository event, on a mention, or when a script invokes it.

The file

An automation is one YAML file in your repository. Any .yaml or .yml file under agents/, .agents/, ellipsis/, or .ellipsis/ with a top-level ellipsis: block is one; the version on your default branch is the live automation.

ellipsis:
  version: v1
  name: Recent work summary

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Find the pull requests merged in web-repo and api-repo in the
    last 7 days and post a summary, under 150 words, to the #eng
    channel in Slack. Ground every line in a real PR.

trigger:
  type: cron
  schedule: "0 9 * * 1"

environment: cloud_agent_environment

permissions:
  github:
    permissions: read_only

budget:
  session: 1.00

Four blocks carry the definition. ellipsis.name is how the automation appears everywhere and what you invoke it by. claude (or codex, which selects the Codex harness) is the persona: the system prompt and the model. trigger decides when it runs. environment names a saved environment or carries an inline block. Everything else has a default; every field is on the agent.yaml reference.

Triggers

A file declares at most one trigger. With none, the automation runs only when invoked.

Trigger	Fires when
`cron`	On a schedule: a five-field cron expression in UTC, or an EventBridge `rate()` / `cron()`. Each fire is a fresh single-turn session.
`react`	On one surface's events: `pull_request`, `push`, `issue`, `linear_issue`, `sentry`, or `slack_channel`, each with its own filters (repositories, branches, paths, labels, author). Each event is a fresh single-turn session, and every matching automation runs independently.
`mention`	When `@ellipsis` is mentioned on GitHub or Linear. Replaces the built-in responder on the platforms it claims. Each surface is one durable conversation.

Slack mentions and DMs are routed by a separate slack.yaml in your .ellipsis repository, per channel and per person: Build a custom Slackbot. Sentry alerts start at most one investigation per issue every 6 hours.

trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [api-repo]
    paths: ["migrations/**"]

Filters and actions per surface: agent.yaml › trigger.

Run it

Invoking an automation runs it exactly as defined: its prompt, model, environment, permissions, and budget bind. A caller supplies only its typed input, an optional lower budget, and metadata.

agent automation run recent-work-summary

curl -X POST https://api.ellipsis.dev/v1/automations/recent-work-summary/sessions \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"issue": "ENG-42"}, "budget": 3.0}'

input is required when the automation declares input.json_schema and refused when it does not; it is validated at the door and rendered into the first message through the automation's input.message template. budget may only lower the automation's own session budget. For a prompt of your own in an environment, start a session instead.

The dashboard's Automations page has the same Run button, and every session an automation starts is listed under it.

Deploy by git

Ellipsis syncs automations on every push to your default branch. There is no deploy step.

You push	Ellipsis does
A new file	Registers the automation: its trigger is armed and any schedule starts.
An edit	Updates it. The next session runs the new version; a running session keeps the version it started with.
A rename, content unchanged	Keeps the same automation, history and schedules included.
A delete	Retires it. No future sessions; past sessions stay readable. Re-adding the file at the same path revives it.
An invalid edit	Keeps the last good version running, shows the error on the dashboard, and emails the author of the commit.

ellipsis.enabled: false turns an automation off without deleting it: no trigger fires, and a manual run from the dashboard still works.

A pull request that edits an automation previews it: sessions that pull request triggers run the branch's version, and Ellipsis comments the exact validation error if the branch breaks the file. Previews apply on private repositories, for same-repository pull requests by authors with write access. For a cron automation nothing on the pull request will trigger, run the file directly: agent -f agents/recent-work-summary.yaml.

The file is the whole definition, so review, history, and rollback are git's: a change is a pull request, git log agents/recent-work-summary.yaml is the changelog, and git revert is rollback.

Without a file

An automation can also live in the API alone: created with POST /v1/automations (or agent automation create -f), live as soon as the call returns, changed with PUT. managed_by says which mode it is in, and only an API-managed automation accepts API edits; one defined by a file is refused, since the next push would undo the change.

Neither mode is a dead end. link opens a pull request adding the file to a repository and hands the automation over when it merges. unlink takes it back under API control and leaves the file inert. Same id, same history, same sessions either way.

agent automation create -f agents/recent-work-summary.yaml   # live at once, no file in git
agent automation link recent-work-summary --repo api-repo    # move it into a repository

Every operation: Automations API and CLI automations.

The file

Triggers

Run it

Deploy by git

Without a file

On this page