agents-ai

Discover and manage AI coding agents from community registries — across Claude Code, OpenCode, Cursor, VS Code (Copilot), and Windsurf.

English · Español

agents-ai is a single CLI to find, install, update, and remove AI coding agents (and rule files) for the editors and assistants you actually use. Browse a community registry interactively, install with one command, and keep your agents in sync over time with a built-in lockfile.

Why

Every AI coding tool has its own conventions for "custom agents" or "rules" — Claude Code uses ~/.claude/agents/, OpenCode uses ~/.config/opencode/agents/, Cursor uses .cursor/rules/, Copilot uses .github/agents/, Windsurf uses .windsurf/rules/.

Discovering good agents is hard. Installing them in the right place is tedious. Keeping them up to date is worse.

agents-ai solves all three with one shared registry and one consistent workflow.

Quick start

No install required:

npx @ruben-salas20/agents-ai list

Or install globally:

npm i -g @ruben-salas20/agents-ai
agents-ai list

Supported tools

| Tool | Project scope | Global scope | Default file extension | | ------------------- | --------------------- | --------------------- | ---------------------- | | Claude Code | .claude/agents/ | ~/.claude/agents/ | .md | | OpenCode | .opencode/agents/ | ~/.config/opencode/agents/ | .md | | Cursor | .cursor/rules/ | — | .md | | VS Code (Copilot) | .github/agents/ | ~/.copilot/agents/ | .agent.md | | Windsurf | .windsurf/rules/ | — | .md |

Tools are auto-detected by probing their root config directory. Environment variables (CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR, XDG_CONFIG_HOME) and per-tool overrides are respected.

Commands

list — browse agents

agents-ai list                          # interactive TUI (in a TTY)
agents-ai list --category engineering   # filter by category
agents-ai list --query react            # full-text search
agents-ai list --tag testing            # filter by tag
agents-ai list --limit 10 --page 2      # paginate

When list runs in a real terminal with no flags, it opens an interactive browser. In CI, pipes, or with any flag, it falls back to plain text output.

search — quick keyword search

agents-ai search react
agents-ai search testing

add — install an agent

agents-ai add engineering/frontend-dev
agents-ai add engineering/frontend-dev -y           # skip prompts
agents-ai add engineering/frontend-dev --global     # global scope
agents-ai add engineering/frontend-dev -a opencode  # specific tool

add shows a pre-install summary (target tools, paths, file extensions) and asks for confirmation. The selector always lists every supported tool for the chosen scope, even if the directory doesn't exist yet — agents-ai will create it.

installed — see what's installed

agents-ai installed

Shows every agent installed locally, grouped by tool and scope.

update — refresh installed agents

agents-ai update                        # check both scopes
agents-ai update engineering/frontend-dev
agents-ai update --global               # global scope only
agents-ai update --project              # project scope only
agents-ai update --force                # also overwrite local modifications
agents-ai update -y                     # skip confirmation

update uses a lockfile (~/.agents-ai/lock.json) to do 3-way drift detection between the local file, the version originally installed, and the upstream version:

| State | Meaning | Action | | ------------------ | ----------------------------------------------------------------------- | ----------------------- | | current | Local matches lockfile and upstream | Skip | | updatable | Upstream changed; local untouched | Re-install | | modified-locally | You edited the file; upstream unchanged | Skip (use --force) | | conflict | You edited the file AND upstream changed | Skip (use --force) | | missing | File was deleted but lockfile entry remains | Re-install |

remove — uninstall an agent

agents-ai remove frontend-dev

Lists the matching installed files across all scopes and asks before deleting.

How it works

bin → commands → core → utils

• Registry — fetches agent metadata from the official registry (with agency-agents as a fallback). Results are paginated and cached per session.
• Detector — probes each tool's root config directory and resolves the right agents/ (or rules/) path per scope, honoring env-var overrides.
• Installer — downloads the agent's .md file from the registry and writes it to every selected target with the tool's correct file extension.
• Lockfile — every install records (slug, source, tool, scope, filePath, sourceHash, installedAt) in ~/.agents-ai/lock.json. update uses these hashes for drift classification.

The TUI (list browse mode) is built with @inquirer/prompts and renders a paginated, filterable view of the registry.

Requirements

• Node.js 18 or newer
• A supported AI coding tool installed (or you can target one explicitly with --agent)

Development

git clone https://github.com/ruben-salas20/agents-ai
cd agents-ai
npm install
npm test
node bin/agents-ai.js list

The project uses Vitest for testing and follows a strict layered architecture (bin → commands → core → utils). Core modules are pure and independently testable.

Contributing

Contributions are welcome — bug reports, new tool support, improvements to the registry client, docs, anything.

1. Open an issue describing the change before opening a PR for non-trivial work.
2. Keep PRs small (≤ 400 changed lines) and tied to a single concern.
3. Add tests for new behavior; existing tests must keep passing.

If you'd like to add support for a new AI coding tool, look at src/core/detector.js — adding an entry to the AGENTS registry there is usually all that's needed.

License

MIT — © Rubén Salas · [email protected]