adding-an-agent.md

Adding an agent

This project's claim is that supporting one more agent costs one more TOML file. This page is that claim, walked end to end, because a claim nobody has written down is a claim nobody can check.

Nothing here needs Rust. The profiles are runtime data, not compiled in: dropping a file into ~/.aviary/profiles/ adds an agent to your own installation immediately, and the same file in crates/aviary-profile/profiles/ adds it for everybody.

There are two halves and they are independent. A config profile says where an agent keeps its settings and what shape they are in. A history provider says where it keeps its conversations. Either is useful alone — see the conversations column in support.md, where several agents are read on one side and not the other.

1. Find out what is there

aviary discover

Lists directories that look like an agent Aviary has no profile for. It is looking for the shape of a config tree, so it finds things nobody has written a profile for yet — which is the point.

2. Take the draft

aviary discover --draft someagent > ~/.aviary/profiles/someagent.toml

The draft is a starting point with the paths it actually found, not a template with placeholders. It loads immediately, so you can run aviary inventory and see what it makes of the agent before changing anything.

verified = false is in there, and it should stay false until step 5.

3. Fill in the shapes

The one field that needs judgement is shape, on each [[entity]]: it names how that agent stores a list of hooks or servers. Eight shapes cover the twenty-one agents surveyed so far, and the draft guesses from what it read. If the guess is wrong, aviary inventory shows it — entries missing, or one entry where there should be four.

Read a neighbouring profile rather than the schema first. claude.toml is the largest and covers most of the cases; codex.toml is TOML instead of JSON; cursor.toml is a short one.

4. Answer the two behavioural questions, or leave them blank

These are the newest fields and the most commonly empty. Both describe behaviour Aviary cannot observe, so both default to "nobody established this", and the interface says so rather than guessing.

# On the profile: does this agent notice a change without being restarted?
#   unknown | immediate | next-session | restart
reload = "next-session"

# On each [[file]]: which one wins when two declare the same setting. Higher takes effect.
[[file]]
role = "settings"
path = "${HOME}/.someagent/settings.json"
precedence = 10

[[file]]
role = "settings-local"
path = "${HOME}/.someagent/settings.local.json"
precedence = 20

Leave them out if you do not know. A blank is honest and the interface handles it; a guess makes Aviary tell somebody a change is live when the agent read its settings at startup, and they will spend an hour debugging the wrong thing. Evidence means the agent's own documentation, or watching it: change a value, see whether a running session picks it up.

Right now one profile of forty-six answers either question — the same one answers both. These are the smallest useful contributions in the repository, and each one is a line.

5. Check it against a real installation, then say so

verified = true means exactly one thing: somebody ran this against an installed copy of the agent and the paths were where the profile says. It is not a quality rating, and it is what the interface shows when it labels a row as unverified.

cargo test --workspace --tests
cargo clippy --workspace --all-targets
node crates/aviary-tauri/ui/check.mjs
python3 scripts/build-corpus.py --check
cargo run -p aviary-cli -- support > docs/support.md

The last line is not optional: a test compares docs/support.md against what the profiles generate, so adding an agent without regenerating it fails the build. That is deliberate — the support table is the one place this project makes a claim about its own coverage, and it should not be possible to widen the claim without the table following.

Two of those gates are about the corpus rather than your profile. If you added a fixture, see scripts/anonymize.example.toml: the corpus is committed to a public repository and a test walks every tracked file asserting no real account, tool or path names survive.

Adding a history provider

Same shape, in crates/aviary-history/providers/. The field worth knowing about first is agent: the config profile this is the history of, when the two are not spelled the same — cursor-ide is the history of cursor, amazonq of amazon-q. - means this provider has no config side at all, which is true of vscode.

Two things a provider commonly gets wrong, both already recorded in crates/aviary-history/src/:

• How token counts accumulate. Some agents write a per-message delta and some write a running total. Summing a running total turns a 178,000-token conversation into millions. usage.mode = "sum" | "last".
• Whether input already includes cached tokens. Adding cache to an input figure that contains it double-counts. usage.input_includes_cache.

Both are declared because both differ between agents that otherwise look identical, and getting either wrong produces a number that is confidently wrong rather than obviously missing.