Automations

An automation saves a prompt, a harness, an environment, permissions, and a budget. Each invocation starts a new session. A trigger makes it run automatically.

Define an automation

ellipsis:
  name: test-repair

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Fix one failing test without
      weakening its assertions. Run the affected tests again
      and open a pull request with the change and test results.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  budget:
    session: 5

This automation attempts a test repair and opens a pull request when it has a fix. It has no trigger, so it runs only when invoked.

Deploy from git

Commit a .yaml or .yml file anywhere under .ellipsis/ on the default branch. Ellipsis syncs it and shows it on the dashboard's Automations page.

The organization can also keep shared definitions in a repository named .ellipsis. That repository's root is the configuration directory.

Invalid updates keep the last valid definition running. Inspect the automation's page for the validation error and source commit. Deleting its file disables the synced automation.

Create through the API

POST /v1/automations creates an automation immediately, without a repository file. Send the definition under automation.

Each automation is managed by git or the API. Edit git-managed definitions in their repository. Use link to open a pull request that moves an API-managed definition into git; use unlink to make a git-managed definition editable through the API.

Run an automation

Choose Run on its dashboard page, or invoke it with a prompt:

curl https://api.ellipsis.dev/v1/automations/test-repair/sessions \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Investigate the request validation tests."
}'

An automation with an input schema requires input instead of prompt. The optional request budget can lower the saved session budget.

Invocation runs once and closes the session after its first turn. Saved automation invocation currently supports Claude Code.

Add a trigger

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

This runs every Monday at 09:00 UTC. An automation accepts at most one trigger.

Use Triggers for event filters and schedules, or Automation schema reference for complete examples.

Handlers

Handlers configure responses to Slack, GitHub, or Linear mentions, and investigations of Sentry alerts. Each account has at most one handler per service, defined by slack.yaml, github.yaml, linear.yaml, or sentry.yaml at the root of its .ellipsis repository. Each file defines service filters and one session block with its harness, prompt, environment, permissions, skills, and budget.

Handlers support the same budget fields as automations: session caps one session, while day, week, and month cap spend across that handler's sessions.

Open Handlers in the dashboard sidebar to see all synced handlers in a table. Select a handler to browse its source file, sync status, documentation, session counts, cost, and sessions. The time range applies to both metrics and the session list.

curl https://api.ellipsis.dev/v1/handlers \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

The response's handlers array contains each synced handler's ID, service, parsed configuration, original YAML, source file, and sync status. Disabled handlers are included. A failed update returns the last valid definition with last_sync_error; a file with no successfully synced definition is omitted. Edit handlers in GitHub.

Use the handler ID to find the sessions it started.

Read a handler's metrics with GET /v1/handlers/{handler_id}/metrics. Optional start and end timestamps select sessions by creation time, including start and excluding end. The response includes counts by current session status and total cost in millicents. Older sessions without that saved handler ID are excluded.