mirror of
https://github.com/tiennm99/awesome-ai-dev-tools.git
synced 2026-10-11 03:13:05 +00:00
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.
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# Contributing
|
|
|
|
## Adding an Agent
|
|
|
|
Edit [`data/agents.yml`](../data/agents.yml) and add an entry:
|
|
|
|
```yaml
|
|
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.yml` only (do not edit `README.md` or `data/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](./LOCAL_DEV.md).
|