Automatic Claude Code plugin discovery for npm dependencies.
npm install ai-readyAutomatic Claude Code plugin discovery for npm dependencies.
ai-ready automatically discovers and enables Claude Code plugins bundled within your npm dependencies. When you install a package that includes a Claude Code plugin, ai-ready detects it and configures Claude Code to load it—no manual setup required.
``bash`
npm install -g ai-ready
1. Install a package with a Claude Code plugin
2. Run air sync in your project
3. Restart Claude Code
4. The plugin is now active!
#### air plugins view [path]
Show plugins discovered in the current project (or specified path).
`bash`
air plugins view
air plugins view /path/to/project
#### air plugins view --all
Show all plugins configured in Claude Code (not just current project).
`bash`
air plugins view --all
#### air plugins sync [path]
Discover and enable plugins from dependencies.
`bash`
air plugins sync
air plugins sync --quiet # For use in hooks
#### air sync (shortcut)
Alias for air plugins sync. Provided for convenience and backward compatibility.
`bash`
air sync # Same as 'air plugins sync'
air sync --quiet
Run air sync (or equivalently air plugins sync) to scan your project's dependencies for Claude Code plugins and automatically enable them:
`bash`
air sync # == air plugins sync
This command:
- Scans node_modules for packages containing .claude-plugin/marketplace.json
- Updates to register discovered plugins
- Respects user choices (won't re-enable plugins you've disabled)
Development workflow: After running npm install to add new dependencies, run air sync and restart Claude Code. Any plugins bundled in your new dependencies will be automatically available.
For fully automatic discovery, configure Claude Code to run air sync --quiet on session start via a hook. See the Claude Code hooks documentation for details.
To bundle Claude Code plugins with your npm package:
1. Create .claude-plugin/marketplace.json:
`json`
{
"name": "my-library-marketplace",
"owner": {
"name": "Your Name or Organization"
},
"plugins": [
{
"name": "my-library-helper",
"source": "./plugins/helper",
"version": "1.0.0",
"description": "Helps developers use my-library APIs"
}
]
}
2. Add your plugin code to .claude-plugin/plugins/helper/ (or wherever source points)
3. Optionally add a plugin.json manifest in each plugin directory:
`json`
{
"name": "my-library-helper",
"version": "1.0.0",
"description": "Helps developers use my-library APIs",
"commands": "./commands/",
"agents": ["./agents/helper-agent.md"]
}
4. Publish your package
Users who install your package will automatically get your plugins enabled via air sync.
The marketplace.json file follows the Claude Code Plugin Marketplace schema:
| Field | Required | Description |
|-------|----------|-------------|
| name | Yes | Marketplace identifier (kebab-case) |owner
| | Yes | Marketplace maintainer info ({name, email?, url?}) |plugins
| | Yes | Array of plugin entries |metadata
| | No | Optional description, version, pluginRoot |
Each plugin entry in the plugins array:
| Field | Required | Description |
|-------|----------|-------------|
| name | Yes | Plugin identifier (kebab-case) |source
| | Yes | Relative path or source object |version
| | No | Plugin version (semver) |description
| | No | Brief plugin description |author
| | No | Plugin author info |commands
| | No | Custom command paths |agents
| | No | Agent definition paths |hooks
| | No | Hook configuration |mcpServers
| | No | MCP server configuration |
1. Discovery: Scans direct dependencies (from package.json) for packages with .claude-plugin/marketplace.json
2. Settings Update: Non-destructively updates
3. Respect User Choice: Never re-enables plugins that users have explicitly disabled
`bashInstall a package with a Claude Code plugin
npm install @anthropic/sdk-helper
Development
bash
Clone the repository
git clone https://github.com/liquid-labs/ai-ready
cd ai-readyInstall dependencies
npm installRun tests
npm testBuild
npm run build
``Apache-2.0