plugins
Version:
Install open-plugin format plugins into agent tools
113 lines (75 loc) • 4.07 kB
Markdown
# plugins
Install plugins into agent tools. Works with [Claude Code](https://code.claude.com) and [Cursor](https://cursor.com).
```bash
npx plugins add owner/repo
```
## Usage
### Add plugins from a GitHub repo
```bash
# GitHub shorthand
npx plugins add vercel/vercel-plugin
# Full HTTPS URL
npx plugins add https://github.com/vercel/vercel-plugin
# SSH URL (auto-retries via HTTPS if SSH auth fails)
npx plugins add git@github.com:vercel/vercel-plugin.git
```
### Add plugins from a local directory
```bash
npx plugins add ./my-plugins
npx plugins add /absolute/path/to/plugins
```
### Discover plugins without installing
```bash
npx plugins discover owner/repo
```
### List detected agent tools
```bash
npx plugins targets
```
## Commands
| Command | Description |
| --------------------------- | ----------------------------------------------------- |
| `plugins add <source>` | Discover and install plugins from a source |
| `plugins discover <source>` | Inspect plugins without installing (dry run) |
| `plugins targets` | List available agent tools and their detection status |
If no subcommand is given, `plugins <source>` defaults to `add`.
## Flags
| Flag | Short | Default | Description |
| ---------- | ----- | ----------- | ---------------------------------------------------------- |
| `--target` | `-t` | auto-detect | Install to a specific agent tool (`claude-code`, `cursor`) |
| `--scope` | `-s` | `user` | Installation scope: `user`, `project`, or `local` |
| `--yes` | `-y` | `false` | Skip the confirmation prompt |
| `--help` | `-h` | | Show usage information |
## Supported targets
The CLI auto-detects which agent tools are installed and installs to all of them.
| Target | Detection |
| -------------------------------------- | ------------------------------------ |
| [Claude Code](https://code.claude.com) | `claude` binary on PATH |
| [Cursor](https://cursor.com) | `cursor` + `claude` binaries on PATH |
## How it works
### Source resolution
The CLI accepts GitHub shorthand (`owner/repo`), HTTPS URLs, SSH URLs, or local paths. Remote repos are shallow-cloned to `~/.cache/plugins/<slug>`. SSH URLs that fail automatically retry via HTTPS.
### Plugin discovery
Discovery follows a 3-step fallback:
1. **Marketplace index** — looks for a `marketplace.json` that indexes multiple plugins
2. **Root plugin** — checks if the repo root itself is a plugin
3. **Recursive scan** — scans subdirectories (up to 2 levels deep) for plugin directories
A plugin is any directory containing skills, commands, agents, rules, hooks, MCP servers, or LSP servers.
### Installation
The CLI translates the vendor-neutral `.plugin/` format into target-specific formats, then installs via the target's native plugin system. Plugin authors write once; the CLI handles the rest.
## Environment variables
| Variable | Purpose |
| ------------------- | -------------------------------------------------------------------------------- |
| `DISABLE_TELEMETRY` | Disable anonymous install telemetry |
| `DO_NOT_TRACK` | Disable anonymous install telemetry ([standard](https://consoledonottrack.com/)) |
| `NO_COLOR` | Disable color output |
| `FORCE_COLOR` | Force color output |
## Development
```bash
npm install
npm run build
node dist/index.js --help
```
Zero runtime dependencies. Built with [tsup](https://tsup.egoist.dev/) as a single bundled ESM file targeting Node.js 18+.
## License
[Apache 2.0](./LICENSE)