Quick Start

No install required -- run with npx:

npx agentshq add owner/repo

The CLI clones the repo, discovers every agent inside it, detects which IDEs you have installed, and writes each agent in the correct format. One command, all your IDEs.

# Install a specific agent
npx agentshq add owner/repo@agent-name

# Search the registry
npx agentshq find react

# List installed agents
npx agentshq list

# Update everything
npx agentshq update

Or install globally:

npm i -g agentshq
agentshq add owner/repo

How It Works

Source repo                     Your machine
───────────                     ────────────
AGENT.md          ──clone──►    .agents/agents/<name>/AGENT.md   (canonical)
*.agent.md                            │
*.json                                ├──►  .claude/agents/<name>.md
*.toml                                ├──►  .cursor/agents/AGENTS.md
AGENTS.md sections                    ├──►  .github/agents/<name>.agent.md
                                      ├──►  .kiro/agents/<name>.json
                                      └──►  ... (43+ IDEs)

Agents are stored once in a canonical format, then translated and copied to each IDE's native format. No symlinks, no lock-in -- every IDE gets a file it understands natively. Updates and removal are tracked automatically via lock files.

Supported IDEs

Native agent support

| IDE | Format | |-----|--------| | Claude Code | .md with YAML frontmatter | | Gemini CLI | .md with YAML frontmatter | | OpenCode | .md with YAML frontmatter | | GitHub Copilot | .agent.md | | Kiro | .json | | Mistral Vibe | .toml | | Cursor | AGENTS.md sections | | Windsurf | AGENTS.md sections | | Codex | AGENTS.md sections | | Amp | AGENTS.md sections | | Augment | AGENTS.md sections | | Roo Code | AGENTS.md sections | | Cline | AGENTS.md sections | | Goose | AGENTS.md sections | | Junie | AGENTS.md sections | | Antigravity | AGENTS.md sections | | Warp | AGENTS.md sections |

Forward-bet IDEs

26 additional IDEs that don't yet have a native agent format. The CLI copies the canonical AGENT.md so agents are ready the moment support lands: Continue, Replit, Trae, Qwen Code, OpenHands, Kilo Code, Droid, Cortex Code, CodeBuddy, and more.

Commands

Install agents

# From a GitHub repo
npx agentshq add owner/repo

# A specific agent from a multi-agent repo
npx agentshq add owner/repo@agent-name

# From any git URL
npx agentshq add https://gitlab.com/org/repo

# From a local directory
npx agentshq add ./path/to/agents

# Global install (available in all projects)
npx agentshq add owner/repo -g

# Target specific IDEs only
npx agentshq add owner/repo --ide claude-code cursor windsurf

# Install everything, no prompts
npx agentshq add owner/repo --all

# Preview agents in a repo without installing
npx agentshq add owner/repo --list

Search agents

# Interactive search with fuzzy matching
npx agentshq find

# Search by keyword
npx agentshq find typescript

Manage agents

# List project agents
npx agentshq list

# List global agents
npx agentshq list -g

# JSON output
npx agentshq list --json

# Remove interactively
npx agentshq remove

# Remove by name
npx agentshq remove agent-name

# Check for updates
npx agentshq check

# Update all agents
npx agentshq update

Create agents

# Scaffold a new AGENT.md
npx agentshq init my-agent

Command reference

| Command | Aliases | Description | |---------|---------|-------------| | add <source> | a, install, i | Install agents from GitHub, GitLab, any git URL, or a local path | | remove [names] | rm, r | Remove installed agents (interactive picker if no names given) | | list | ls | List installed agents | | find [query] | search, f, s | Search the registry | | check | | Check for available updates | | update | upgrade | Update all agents | | init [name] | | Create a new AGENT.md |

Flags

| Flag | Description | |------|-------------| | -g, --global | User-level scope instead of project-level | | --ide <ides> | Target specific IDEs (or * for all) | | --agent <names> | Select specific agents (or * for all) | | -y, --yes | Skip confirmation prompts | | --all | All agents, all IDEs, no prompts | | --list | Preview without installing | | --json | Machine-readable output |

Publishing Your Own Agents

Repo layout

Single agent -- put an AGENT.md at the root:

my-agent/
  AGENT.md

Multiple agents -- one subdirectory per agent:

my-agents/
  agents/
    code-reviewer/
      AGENT.md
    api-designer/
      AGENT.md
    test-writer/
      AGENT.md

Push to GitHub (or any git host) and anyone can install with npx agentshq add owner/repo.

AGENT.md format

---
name: code-reviewer
description: Reviews pull requests for correctness, style, and security issues
metadata:
  tags:
    - code-review
    - security
  tools:
    - Read
    - Grep
    - Bash
  model: sonnet
---

# Code Reviewer

You are a senior code reviewer. When activated, review the provided
code changes for correctness, security, and style issues.

| Field | Required | Description | |-------|----------|-------------| | name | yes | Agent identifier (used as directory name on install) | | description | yes | One-line summary shown in search results | | metadata.tags | no | Keywords for discovery | | metadata.tools | no | Tools the agent needs | | metadata.model | no | Preferred model hint | | metadata.internal | no | Set true to hide from public discovery |

The markdown body is the agent's system prompt -- preserved verbatim across all format translations.

Supported input formats

The CLI auto-detects all of these:

| Format | Example | Used by | |--------|---------|---------| | AGENT.md | agents/reviewer/AGENT.md | Canonical (recommended) | | <name>.md | reviewer.md with YAML frontmatter | Claude Code, Gemini CLI, OpenCode | | <name>.agent.md | reviewer.agent.md | GitHub Copilot | | <name>.json | reviewer.json | Kiro | | <name>.toml | reviewer.toml | Mistral Vibe | | AGENTS.md | <!-- agent:reviewer --> sections | Cursor, Windsurf, Augment + 8 more |

Private Repos

Same syntax as public repos:

npx agentshq add your-org/private-agents

When the source is private, the CLI automatically:

• Skips all telemetry -- no repo names or agent names leave your machine
• Skips the security audit API -- zero external requests
• Tracks only locally -- lock file entries for updates, nothing more

Set GITHUB_TOKEN or GH_TOKEN if you need token-based access:

GITHUB_TOKEN=ghp_xxx npx agentshq add your-org/private-agents

Requirements

• Node.js >= 18

License

MIT -- see LICENSE for details.