Lifecycle

An agent's lifecycle is git's. The YAML file on your default branch is the live agent, a branch version is a preview, and deleting the file retires it. This page is the exact behavior of each transition; the reasoning behind the model is Agents as code.

agents/recent-work-summary.yaml in splitshift-api

main ──── a41f09 ──────────────────────── f3c9d1 (merge) ────────▶
          live: a41f09                    live: f3c9d1
             │                               │
             │  Mon 09:00 session ran        │  Mon 09:00 session ran
             │  snapshot a41f09              │  snapshot f3c9d1
             │                               │
priya/lower-summary-budget                   │
             └── c8d4e2 ─────────────────────┘
                 budget.session: 1.00 → 0.50
                 not live until merged; PR #482 previews it

Deploy

Every push to the default branch syncs agent configs. Ellipsis scans .yml/.yaml files at any depth under agents/, .agents/, ellipsis/, or .ellipsis/; a file is an agent config when it declares a top-level ellipsis: mapping, and other YAML in those directories is ignored.

"Live" means the trigger is armed: a cron schedule fires, a react trigger matches events, a mention trigger answers. There is no deploy step and nothing to restart.

An invalid edit never takes an agent down. The last good version keeps running, the sync error is shown on the agent in the dashboard, and Ellipsis emails the author of the breaking commit (falling back to the account's contact email) the first time a working config breaks. Push a fix and the error clears.

Creating an agent from the dashboard follows the same path: Ellipsis opens a pull request adding the file under agents/, and the agent goes live when it merges.

Preview

A pull request that adds, edits, or removes an agent config gets previewed on itself: sessions that pull request triggers resolve configs as the repository would have them after the merge. An edited file runs the branch's version, an added file participates, a removed file does not run. Nothing is registered, no schedule changes, and other pull requests and the live agents are untouched.

Previews are gated on trust, since a branch config runs before review. All three must hold, and the gate fails closed:

• The repository is private.
• The pull request is from the same repository, not a fork.
• The author has write access to the repository.

A config the pull request breaks is dropped from that pull request's runs rather than silently falling back to the stale live version, and Ellipsis maintains one comment on the pull request with the exact validation error per file, updated on every push.

Previews only reach agents the pull request itself triggers. For a cron or mention agent, run the branch's file directly instead:

$ agent session start --config-file agents/recent-work-summary.yaml --watch

The session runs the file as written, without touching the deployed agent.

Disable and delete

Turn an agent off without deleting it by merging ellipsis.enabled: false:

ellipsis:
  enabled: false

A disabled agent stops starting sessions from its triggers: cron fires are skipped, react events no longer match it, mentions pass it over. An open conversation stops at its next turn boundary, and messages sent to it hold as pending; re-enable the agent and the next message delivers them. The agent stays in the dashboard with a Disabled badge, and a manual run from the dashboard still works, so you can test a disabled agent before turning it back on.

Deleting the file retires the agent: no future sessions, schedules removed, and the agent drops out of the dashboard. The delete is soft. Past sessions, their logs, and their config snapshots stay intact and readable.

Re-adding a config file at the same path revives the same agent: its identity, session history, and schedules reconnect. Re-adding the same content at a different path registers a new agent with no history.

Version history

Every session freezes the config it runs at launch. The session's Config tab in the dashboard shows that exact snapshot as YAML, with any fields overridden at launch (from the API or CLI) listed separately above it. The saved agent may have changed since; the snapshot is the faithful record of what ran, and for a one-off inline config it is the only record.

Replaying a session reuses its frozen snapshot by default, so agent session replay reproduces the run against the config version that produced it, not today's (CLI sessions).

The agent's own history is git's: git log agents/recent-work-summary.yaml is its changelog, with authors and reasons, and git revert is rollback.