tiennm99
eb12bcc2cb
A single category could not describe tools that ship as a CLI, an editor plugin and a desktop app at once, and 7 of the 40 entries were filed under a surface they only partly match — cline is "an SDK, IDE extension or CLI assistant" in one `extension` slot, Reasonix ships CLI, desktop and VS Code under `cli`, warp is a terminal filed as `ide`. Tags cover five facets: surface (at least one), model access, workflow, integration, and origin (at most one). tagVocabulary in validate.go is the single source of truth — the validator, its error messages, and the dashboard's filter chips all derive from it, the last via a new facets field in site/data.json. The dashboard now filters on tags with multi-select chips grouped by facet: OR within a facet, AND across facets, plus a clear-filters control, and search matches tags as well as name and description. Only tags some row actually carries get a chip, so chips and rows cannot disagree. Tag pills are tinted per facet, replacing the category badge. All 40 entries are tagged from each repo's own README, topics and docs; CONTRIBUTING documents every tag and the evidence rule for applying one. A leftover `category:` key now fails validation with a message naming its replacement, rather than being silently ignored. README.md and data/history.jsonl are the regenerated updater output.
4.8 KiB
Contributing
Adding an Agent
Edit data/agents.yml and add an entry:
agents:
- owner: github-username-or-org
repo: repository-name
tags: [terminal, byo-model, interactive, community]
Required fields: owner, repo, tags
Optional fields: notes (for clarifications or caveats)
Field Reference
| Field | Type | Required | Description |
|---|---|---|---|
owner |
string | Yes | GitHub user or organization that owns the repo |
repo |
string | Yes | Repository name on GitHub |
tags |
list | Yes | Tags from the vocabulary below; at least one surface tag, at most one origin tag |
notes |
string | No | Additional context or disclaimers |
Tag Vocabulary
Tags replaced the old single-select category field, because one slot cannot
describe a tool that ships as a CLI, an editor plugin and a desktop app at the
same time — which most of them now do. An entry carries several tags across
five facets. data/agents.yml is the source of truth; the vocabulary itself
lives in tagVocabulary (validate.go) and reaches the dashboard through
site/data.json, so it is defined exactly once.
Surface — where you run it. At least one required.
- terminal — a CLI or TUI you run in a shell
- editor-plugin — extension for an existing editor (VS Code, JetBrains, Neovim)
- ide — a standalone editor or IDE
- desktop — a native or Electron/Tauri desktop app
- web — runs in a browser, hosted or local
- self-hosted — a server you deploy, with clients or editor plugins on top
Model access — which models it can drive.
- byo-model — bring your own: multiple providers, OpenAI-compatible endpoints, or OpenRouter
- single-vendor — built for one lab's models
- local-models — runs against local inference (Ollama, llama.cpp, vLLM, SGLang)
Workflow — how you work with it.
- interactive — conversational pair programming, you stay in the loop
- autonomous — takes a goal or issue and runs long stretches unattended
- review — reviews diffs or existing code rather than writing it
- app-builder — prompt-to-app scaffolding, with preview and deploy
- research — published as a research artifact or proof of concept
Integration — what it plugs into.
- mcp — speaks Model Context Protocol
- acp — speaks Agent Client Protocol
- headless — a non-interactive mode for scripting or CI
Origin — who publishes it. At most one.
- vendor — first-party tool from a model lab (Anthropic, OpenAI, Google, xAI, DeepSeek, Alibaba, Moonshot, …)
- community — everyone else
The evidence rule
Apply a tag only when the repo's own README, docs, or GitHub topics support it. Do not tag from reputation or from a blog post. Under-tagging is better than a wrong tag: a missing tag hides a row from one filter, a wrong one sends someone to a tool that cannot do what they need.
Deliberately not tags: model names (gpt-4, sonnet, r1) because they
churn within months, and implementation stacks (rust, nextjs) because they
say nothing about choosing the tool. GitHub topics are a drafting aid only —
12 of the tracked repos have no topics at all, including several in the top ten.
Handling Duplicates and Changes
Duplicate repos: CI rejects them. go run . -check fails on a case-insensitive owner/repo match, so a duplicate never reaches a daily run. It also rejects unknown tags, a repeated tag, an entry with no surface tag, two origin tags, and any leftover category: key.
Renamed repos: GitHub redirects the old slug, so the updater keeps working — it prints a ::warning:: naming the new slug. Update owner/repo in data/agents.yml to the new slug and add the old key to canonicalKeyMigrations in history.go, or the repo's star history detaches and its deltas show —.
Deprecation: To remove an agent, delete its entry from data/agents.yml. The next run drops it from the README; its history stays in data/history.jsonl, so re-adding the entry later restores its star chart.
Staleness: An entry with no push in 6 months is dropped. Past 3 months the updater prints a ::warning:: naming the repo and its days idle, so the daily run surfaces candidates without anyone auditing the list by hand. Removal stays a human decision: a repo can go quiet between releases, and a historically significant one (gpt-engineer) is kept with a notes marker instead.
PR Review
- Keep PRs to changes in
data/agents.ymlonly (do not editREADME.mdordata/history.jsonl) - The daily GitHub Actions workflow (runs at 00:00 UTC) picks up merged PRs automatically
- No manual review required; the updater regenerates the README after your PR merges
For local testing before opening a PR, see LOCAL_DEV.md.