All docs
Operate
Plugins
The main repository, Repo registrations and the official plugin; the seed, sync, and how changes take effect.
Everything that can change without a new binary lives in plugins: Repo registrations, roles, workflows, harness definitions, prompts and the UI. A plugin is a Git repository in the plugin directory.
Three kinds of plugin
| Plugin | id | What it is |
|---|---|---|
| Main repository | main |
The global entry point: it registers every other plugin, holds the Journal, and holds your own content |
| Official plugin | official |
The roles, workflows, harness definitions, prompts, Router contract rules and base UI that ship with the system. There is one global set |
| Repo plugin | Set at registration | A Git repository to work in |
The main repository
main/
ail.yaml format version
AGENTS.md notes for Workers dispatched to the main repository
repos/<repo id>.md one registration per Repo
journal/<year>-<month>.md the Journal
skills/<name>/SKILL.md your own ways of working; optional
A Git repository in this format is the whole entry point. On a fresh installation, put its URL into "Main repository"; the Daemon clones it and then clones every repository it registers.
Registering a Repo
repos/<repo id>.md in the main repository, one per Repo:
---
schema: 1
id: billing
name: Billing
description: The billing service and its admin pages
git: git@example.com:team/billing.git
aliases: [bill]
intents: {disable: [upgrade]}
---
Extra notes for the Router and Workers; may be empty.
| Field | Required | Meaning |
|---|---|---|
id |
Yes | Lower-case letters, digits and hyphens; also the directory name in the plugin directory |
name |
Yes | Its name |
description |
Yes | One sentence: what this repository is and what should be dispatched to it. The Router picks a Repo by it |
git |
No | The Git URL. Without it the repository is local only |
aliases |
No | Other names |
meta |
No | The id of the meta repository it belongs to |
intents, roles |
No | {only: […]} or {disable: […]}: which intents and roles this repository accepts or refuses |
archived |
No | true: it no longer appears in the project table and cannot be dispatched to |
Registering a Repo takes at least a Git URL, a name and a description:
ail repo add --git git@example.com:team/billing.git --name Billing --description "The billing service and its admin pages"
All Repos are flat; none is nested. The relation between a meta repository and its members is written only in the member's meta.
The official plugin
official/
workflows.yaml intents, workflows, called roles, a few limits
roles.yaml the binding of every role
harnesses.yaml harness definitions
roles/<role>.md role descriptions
frames/ frames for the first message
prompts/ the global prompt and shared principles
router/contract.md the rules of the Router contract
ui/shell/ the base UI
roles.yaml binds each role to a harness on a Client:
schema: 1
default_client: studio-pc
roles:
router: {harness: codex, model: <model>, thinking: medium}
execute: {harness: codex, model: <model>, thinking: xhigh}
media: {client: media-pc, harness: antigravity, model: <model>}
A binding has four parts: which Client to start on, which harness, which model, how much thinking. model and thinking use the options the harness lists over ACP; they are checked when the session is created, and a wrong value fails.
The seed
A copy of the official plugin ships inside the executable; it is called the seed. When the plugin directory has no official plugin, the Daemon creates a local Git repository, commits the seed on the seed branch and branches main from it. Your changes and the agents' are committed on main.
After a new executable is installed, the Daemon commits the new seed to seed and merges it into main. If there is a conflict or uncommitted work it does not merge; the Config page says so, and you or an agent you dispatch does the merge. An upgrade therefore never overwrites the roles, workflows and UI you changed, and the changes that ship with a new version still reach you.
Sync
ail plugin sync, or the sync button on the Config page: the main repository is fast-forwarded when it can be; missing repositories are cloned from their registrations and the rest fast-forwarded when possible. Nothing is force-pushed and no change is lost; one failing repository does not affect the others.
How changes take effect
| What changed | How it takes effect |
|---|---|
| A Repo registration | Validated; the Router contract is registered again; a newly registered Repo is fetched automatically |
workflows.yaml, roles.yaml |
Validated; the next dispatch and the next step follow the new version; the Router contract is registered again |
harnesses.yaml |
Validated; the next session is created from the new version |
| Role descriptions, frames, prompts | The first message of the next Worker to start is rendered from the new version |
| UI plugin source | The Daemon rebuilds it, open pages are notified, and a refresh shows the new version |
No restart is needed. Workers already started are unaffected: their role description is in their first message.
When a file is malformed, any action that needs it fails at once, and the error says which file and what is wrong. The Router contract and the UI keep the last version that was generated successfully.