Your first agent

Build a working agent in five steps: a weekly summary of the code your team shipped. By the end you will have a config file in your repository, a live agent, and its first run.

The example org throughout these docs is Splitshift, a shift-scheduling product with repos like splitshift-web and splitshift-api. Substitute your own repository names.

1. Create the file

Agents live in your repository under agents/. Create agents/recent-work-summary.yaml with the agent's identity and instructions:

ellipsis:
  version: v1
  name: Recent work summary
  description: A weekly summary of the code changes we shipped

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Use the GitHub tools to find the pull requests merged in the
    last week and summarize what the team has been working on.
    Keep it under 150 words and grounded in what the tools
    returned. Never invent activity.

The ellipsis: block is what marks the file as an agent config. claude.system is the instruction the agent follows on every run; claude.model picks the model. GitHub tools are available automatically.

2. Choose when it runs

Add a trigger. This one fires every Monday at 09:00 UTC:

triggers:
  - type: cron
    schedule: "0 9 * * 1"

An agent can also run when repository or Linear events happen (react) or when someone mentions @ellipsis (mention). A config with no triggers still runs on demand from the CLI, API, or dashboard.

3. Point it at your code

List the repositories cloned into the agent's sandbox:

sandbox:
  repositories:
    - name: splitshift-web
    - name: splitshift-api

4. Cap what it can spend

Budgets are in US dollars. run caps a single run; week caps this agent's trailing 7-day spend:

limits:
  run: 1.00
  week: 2.00

The complete file:

ellipsis:
  version: v1
  name: Recent work summary
  description: A weekly summary of the code changes we shipped

claude:
  model: claude-haiku-4-5-20251001
  system: |
    Use the GitHub tools to find the pull requests merged in the
    last week and summarize what the team has been working on.
    Keep it under 150 words and grounded in what the tools
    returned. Never invent activity.

enabled: true

triggers:
  - type: cron
    schedule: "0 9 * * 1"

sandbox:
  repositories:
    - name: splitshift-web
    - name: splitshift-api

limits:
  run: 1.00
  week: 2.00

5. Deploy it

Commit the file to your default branch:

git add agents/recent-work-summary.yaml
git commit -m "Add weekly work summary agent"
git push

Ellipsis syncs the file on push, registers the agent, and starts the cron schedule. (The dashboard offers the same flow in reverse: it opens the pull request that adds this file for you.)

Run it once now instead of waiting for Monday:

agent config list                             # find the config's id
agent run start --config agent_x9Kd3Fq2 --watch

Every Monday after this, a run starts on its own. The run's summary reads like:

Merged 9 PRs this week. splitshift-api: shift-trade requests now
expire after 48h (#412), fixed a double-booking race in schedule
assignment (#418). splitshift-web: managers can bulk-assign open
shifts (#87). One revert: #415 reverted #409 (timezone handling).

Iterate

The file is the source of truth. Edit the YAML and push, and the agent updates on sync; delete the file and the agent is removed. See Agents as code for the sync model and Agent config for every field.