The agent matrix is a read-only capability view that joins the curated agent registry with your local usage statistics. It powers the recommendation badges you see when starting a feature while maintainer-owned tooling keeps pricing, scores, notes, and quarantine state current.
What the matrix contains
For every (agent, model) pair registered in templates/agents/<id>.json, the matrix tracks:
| Field | Source | Description |
|---|---|---|
pricing | Registry | Public API cost in $/M tokens (inputPerM, outputPerM) |
notes.<op> | Registry | Human-readable capability note for each operation |
score.<op> | Registry | Qualitative score 1–5 for each operation |
lastRefreshAt | Registry | When this entry was last refreshed by maintainer tooling |
stats | Local telemetry | Features run, total cost, sessions for this model |
The four operations are: draft, spec_review, implement, review. Scores and notes can differ per operation — a model that excels at implementation may score lower for spec writing.
Recommendation badges in the start modal
When you open the start modal for a feature, Aigon calls /api/recommendation/:type/:id to rank available agents for the relevant operation. The top candidates are shown alongside the agent/model dropdowns:
- ✨ Best value — highest score-to-cost ratio
- ⚡ Fastest — lowest latency / cost for this operation
- 🎯 Highest quality — highest qualitative score for this operation
Badges are suggestions only. The user still picks the agent and model — the recommender never overrides your choice.
Cells with no benchmark data (zero sessions) fall back to qualitative score alone and show confidence: low in the ranking rationale. The recommender never invents numbers to fill empty cells.
How ranking works
The score for each (agent, model, operation) triplet is:
score = qualitative_score (1–5) − cost_penalty (normalised $/op)qualitative_score comes from score.<op> in the agent registry. cost_penalty is derived from actual session cost in your local telemetry (stats-aggregate.perTriplet). Quarantined models are excluded from ranking by default.
Keeping the matrix current
OSS Aigon ships curated registry data in templates/agents/*.json and exposes it through Settings, model pickers, and recommendation APIs. Benchmark sweeps, model discovery, registry refresh, and direct registry mutation are maintainer-owned workflows outside the OSS user CLI.
Agent registry fields reference
In templates/agents/<id>.json, each entry in cli.modelOptions[] can carry:
{
"value": "claude-opus-4-7",
"label": "Opus 4.7",
"pricing": { "inputPerM": 15.0, "outputPerM": 75.0 },
"notes": {
"implement": "Strong on multi-file reasoning and architecture decisions.",
"review": "Thorough but slow — best for high-stakes reviews."
},
"score": {
"draft": 4,
"spec_review": 5,
"implement": 5,
"review": 5
},
"lastRefreshAt": "2026-04-20T10:00:00.000Z"
}Models with quality or safety issues can be marked quarantined rather than deleted:
{
"value": "some-model",
"quarantined": { "reason": "Hallucinated test output in F358", "since": "2026-03-15" }
}Quarantined models are excluded from recommendations and shown with a warning in the Settings tab matrix view.