awesome-ai-dev-tools/docs/CONTRIBUTING.md

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

Scope

This list ranks developer tools built around AI — things a developer uses to build software, where an LLM is central to what the tool does. In practice that spans several shapes:

• Coding agents — they write, edit, or review code themselves.
• Agent development environments (ADEs) — their primary purpose is running and coordinating those agents: parallel worktrees, session management, remote or mobile control. Tag these orchestration.
• AI-assisted editors, terminals, and review tools — the developer stays in the driver's seat and the model accelerates the work.

The dividing line is tools you use vs. building blocks you import. Out of scope: libraries and SDKs, agent frameworks meant to be built on, model weights, prompt or skill collections, and dashboards that only observe a tool without being one.

A tool also has to be about software development. General-purpose assistants and chat UIs do not qualify just because a developer could use them.

The star floor is hard

1,000 stars minimum. This is not a judgement call and is not waived for individual entries, however good the tool is. The updater enforces it: any entry below the floor is dropped from the ranking and reported as an ::error:: in the Actions log (enforceStarFloor in github.go). Because star counts require the API, go run . -check cannot catch this offline — a below-floor entry passes CI and is then dropped by the next daily run, so check the count before opening a PR.

Maintenance requirements apply to every entry equally: no push in 6 months means removal, and the daily run warns past 3 months.

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
• orchestration — runs and coordinates other coding agents as its primary purpose (an ADE), rather than editing code itself

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.