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:

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 list                     # list everything in the registry
autoagents list --tags laravel      # filter list by tag
autoagents status                   # show what's installed
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 uses .claude/ as the canonical install prefix; the CLI rewrites it to .cursor/, .windsurf/, etc. based on what you have.
• 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 \
AUTOAGENTS_REGISTRY_BRANCH=staging \
AUTOAGENTS_HOME=/path/to/state-dir \
npx autoagents

Where things land

Install targets are framework-adapted from the canonical .claude/ prefix:

• Claude Code → .claude/agents/<name>.md
• Cursor → .cursor/agents/<name>.md
• Windsurf → .windsurf/agents/<name>.md
• Codex → .codex/agents/<name>.md

Local state

AutoAgents tracks installs in SQLite at ~/.autoagents/registry.db. Nothing leaves your machine.

Browse the registry