Automation schema reference

For an introduction and setup instructions, see Automations.

An automation has four top-level blocks: ellipsis, optional trigger, optional input, and session. Unknown fields fail validation.

Scheduled test checks

ellipsis:
  name: nightly-tests
  description: Check the API test suite every night

trigger:
  type: cron
  schedule: '0 2 * * *'

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Report failures with the test
      name and error. Do not modify code.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  permissions:
    github:
      permissions: read_only
  budget:
    session: 3
    day: 10
    week: 50

The session records test results each night at 02:00 UTC.

React to a pull request

ellipsis:
  name: check-api-changes

trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [api-repo]
    paths: ['src/routes/**']
    draft: false

session:
  claude_code:
    prompt: |
      Check the changed API routes for missing test coverage.
      Add focused regression tests where needed, run them,
      and report the results.
  environment:
    repositories:
      - name: api-repo
    hooks:
      after_checkout: |
        cd /sandbox/api-repo
        npm ci
  budget:
    session: 5

A matching head update starts a session. Repository filters decide which events match; the environment decides which repositories are available.

Typed input and output

ellipsis:
  name: classify-change

input:
  json_schema:
    type: object
    properties:
      description:
        type: string
    required: [description]
    additionalProperties: false
  message: 'Classify this change: {{description}}'

session:
  claude_code:
    prompt: |
      Classify the requested change as bugfix, feature, or maintenance.
      Explain the classification in one sentence.
    model: claude-opus-5
  output:
    json_schema:
      type: object
      properties:
        category:
          type: string
          enum: [bugfix, feature, maintenance]
        reason:
          type: string
      required: [category, reason]
      additionalProperties: false
  budget:
    session: 1

Invoke with {"input":{"description":"Reject expired reset tokens"}}. Read the validated result from GET /v1/sessions/{session_id}/output.

Structured output is available with every supported Claude and OpenAI model. Use the model's matching harness (claude_code or codex); GET /v1/account/models lists each model's capabilities. An invocation cannot provide both input and prompt.

Workflow prompt

Put the task in the selected harness's prompt string:

ellipsis:
  name: backend-task

session:
  claude_code:
    prompt: |
      Read docs/engineering.md in api-repo and follow its conventions.
      Run the relevant tests before finishing.
  environment:
    repositories:
      - name: api-repo
  budget:
    session: 5

The prompt becomes user input. On an invocation with structured input or a triggering event, the initial message also includes that context.

Codex skills

Declare a directory containing SKILL.md to give Codex a reusable procedure and its supporting files:

session:
  codex:
    prompt: Use the release-checks skill to review the release.
    model: gpt-5.6-terra
  skills:
    - path: skills/release-checks
      repository:
        name: api-repo

Codex receives the skill and can read its references or run its scripts. SKILL.md needs YAML frontmatter with a nonempty description; name defaults to the directory name and must fit 64 characters.

A skill uses the repository's checkout revision when that repository is in the session. Otherwise, repository.ref selects a revision, or the repository's default branch is used. A bare path uses the automation's source repository, falling back to the first session repository for inline configurations. Use an explicit repository for sessions without either.

Skills are resolved again when a session resumes. Missing files, inaccessible repositories, invalid metadata, and size-limit violations fail the session. Each skill allows up to 50 UTF-8 files, 64 KiB per file, and 512 KiB total. A session can declare up to 10 skills.

Identity and triggers

In a template, {{field}} reads the caller's input. Triggered work can reference event fields with {{field}}. References must exist in the declared input or trigger schema.

Session settings

See Models, Environment schema reference, and Permissions.

Budgets

session:
  claude_code: {}
  budget:
    session: 5
    day: 20
    week: 100
    month: 300

Values are US dollars. day, week, and month cover trailing 1-, 7-, and 28-day windows. They measure this automation's spend.

Handlers use the same session.budget fields in slack.yaml, github.yaml, linear.yaml, and sentry.yaml. A handler's trailing limits measure spend across all its sessions, including sessions started from earlier revisions of that handler. Each handler has its own limits. An omitted trailing limit inherits the same platform ceiling as an automation.

Account and developer limits also apply. Limits stop new paid requests; in-flight requests and sandbox teardown can add usage after a threshold is reached.