Documentation

AutoAgentsis a tiny CLI that does one thing: scan your project, fetch the matching community-curated specialist agents, and install them into your AI assistant's config directory.

Install

No install needed — just run:

$npx autoagents

Or install globally with npm install -g autoagents.

Commands

autoagents                          # scan + install for cwd
autoagents /path/to/project         # for a specific path
autoagents --dry-run                # show what would be installed
autoagents --tags react,tailwind    # force-include tags
autoagents --items nextjs-specialist # install a specific agent only
autoagents --scan-only              # show detected tags, install nothing
autoagents --related                # include related tags
autoagents --no-verify              # skip checksum verification (not recommended)

autoagents scan                     # show detected tags + framework
autoagents scan --json              # JSON output for piping
autoagents plan --json              # deterministic matches + reasons
autoagents suggest                  # explicit optional suggestions
autoagents list                     # list everything in the registry
autoagents list --tags laravel      # filter list by tag
autoagents status                   # show what's installed
autoagents update --check           # check updates and local drift
autoagents doctor                   # validate the install
autoagents remove --all             # uninstall everything
autoagents remove --item <name>     # uninstall one

How detection works

Stack signatures — looks at package.json, composer.json,Cargo.toml, pubspec.yaml, requirements.txt, and 50+ other markers to identify your stack.
AI framework — detects .claude/, .cursor/,.windsurf/, .codex/ directories or their associated config files.
Tag matching - each registry item declares tags plus optional explicit match and suggest rules. The CLI installs deterministic matches and keeps broader suggestions separate.
Framework adaptation — the manifest stores one checksum-authenticated, Claude-compatible source. The CLI renders Markdown agents for Claude Code and Cursor, TOML for Codex, or a model-decided workspace rule for Windsurf.
Checksum verification — every fetched file is verified against the SHA-256 in the manifest before being written. Tampered content is rejected with an error.

Configuration

Environment variables (mainly for testing forks):

AUTOAGENTS_REGISTRY_OWNER=my-fork \
AUTOAGENTS_REGISTRY_REPO=autoagents-registry \
AUTOAGENTS_REGISTRY_BRANCH=staging \
AUTOAGENTS_HOME=/path/to/state-dir \
npx autoagents

Where things land

Install targets and content are adapted from the canonical Claude-compatible source:

Claude Code → .claude/agents/<name>.md
Cursor → .cursor/agents/<name>.md
Windsurf → .windsurf/rules/<name>.md as a model-decided rule
Codex → .codex/agents/<name>.toml

Local state

AutoAgents tracks installs in SQLite at ~/.autoagents/registry.db and records per-project drift metadata in .autoagents/installs.json. Project contents are scanned locally and are not uploaded; only registry files and metadata are fetched.

Browse the registry