Agents as code
GitHub is the source of truth; how sync, previews, and deletes work.
Agents are YAML files in your repository, and GitHub is the source of truth: the file on your default branch is the agent. This gives agents everything code has: review before deploy, history, rollback with git revert, and no drift between what is written and what runs.
The sync model
Pushes to the default branch sync agent configs. The canonical directory is agents/; .agents/, ellipsis/, and .ellipsis/ work too, at any depth. A file is a config when it declares a top-level ellipsis: mapping; other YAML in those directories is ignored.
| You push | Ellipsis does |
|---|---|
A new agents/name.yaml | Parses, validates, and registers the agent; starts any cron schedules. |
| An edit to the file | Updates the agent. |
| A rename or move (content unchanged) | Keeps the same agent: identity, history, and schedules carry over. |
| A delete | Soft-deletes the agent and removes its schedules. |
| An invalid edit | Records the sync error and keeps the last good config running. |
The default branch decides
Registered agents always come from the default branch. A pull request branch never registers, edits, or deletes an agent, and a run that already started keeps the config snapshot it began with.
On private repositories, Ellipsis previews config changes on the pull request that makes them: runs triggered by that PR use the PR's version of the config, so you watch an edited agent behave before merging. The preview is never registered, changes no schedules, and applies only to same-repo PRs by authors with write access.
Deleting and reviving
Deleting the file stops future runs and removes the agent from the dashboard; past runs and their config snapshots stay intact. Re-adding a file at the same path revives the same agent: its identity, run history, and schedules reconnect. Re-adding the config at a different path registers a new agent.
The dashboard is a front-end to the same model
Creating an agent in the dashboard does not bypass GitHub: Ellipsis opens a pull request adding the YAML file under agents/, and the agent goes live when it merges. After that, the file is the agent; edit or delete it like any other code.
Validation
The same validator runs everywhere: GitHub sync, the dashboard, and POST /agents/configs/validate. A config fails validation when the ellipsis.version is unsupported (only v1 exists), claude.system is empty on a non-mention agent, a cron expression is invalid, or branches is set on a non-push react event. New files that fail validation are reported and not registered; existing agents keep their last good config.