# AIPM — AI Plugin Manager
[](https://github.com/TheLarkInn/aipm/actions/workflows/ci.yml)
[](https://codecov.io/gh/TheLarkInn/aipm)
A production-grade package manager for AI plugin primitives (skills, agents, MCP servers, hooks). Think npm/Cargo, but purpose-built for the AI plugin ecosystem.
AIPM ships as **two Rust binaries** with **zero runtime dependencies**:
| **`aipm`** | Consumer CLI | `init`, `install`, `update`, `link`, `unlink`, `list`, `lint`, `migrate` |
| **`aipm-pack`** | Author CLI | `init` |
Both work across .NET, Python, Node.js, and Rust projects with no runtime dependency.
## Install
### Shell (Linux / macOS)
```sh
### PowerShell (Windows)
```powershell
> Installers are provided by [cargo-dist](https://opensource.axo.dev/cargo-dist/). Run `aipm-update` to self-update.
### Build from Source
```bash
cargo build --workspace # build all crates
cargo test --workspace # run all tests
```
---
## `aipm` — Consumer CLI
Manages AI plugin workspaces: scaffolding, installing plugins from multiple sources, migrating existing configurations, and linting for quality issues.
### Global Flags
| `-v, --verbose` | Increase verbosity (`-v` info, `-vv` debug, `-vvv` trace); default level is warn |
| `--log-format <FMT>` | Tracing output format on stderr: `text` (default) or `json` |
### `aipm init`
Scaffold a workspace with a `.ai/` local marketplace and tool-specific settings.
```
aipm init [OPTIONS] [DIR]
```
| `-y, --yes` | Skip interactive prompts, use defaults |
| `--workspace` | Generate a workspace-level `aipm.toml` with `[workspace]` section |
| `--marketplace` | Create `.ai/` marketplace directory with tool settings |
| `--no-starter` | Skip the starter plugin (bare `.ai/` directory only) |
| `--manifest` | Generate `aipm.toml` manifests for each plugin (opt-in) |
| `--name <NAME>` | Custom marketplace name (default: `local-repo-plugins`) |
When run on a TTY without `--yes`, launches an interactive wizard.
**What it creates:**
- `.ai/<marketplace-name>/` — local marketplace directory
- `.ai/<marketplace-name>/starter-aipm-plugin/` — starter skill plugin (unless `--no-starter`)
- `.ai/.claude/settings.json` — Claude Code marketplace registration
- `.ai/.copilot/` — Copilot agent settings (if detected)
- `aipm.toml` — workspace manifest (with `--workspace`)
### `aipm migrate`
Migrate existing `.claude/` configurations into marketplace plugins. Detects skills, agents, MCP servers, hooks, commands, and output styles.
```
aipm migrate [OPTIONS] [DIR]
```
| `--dry-run` | Preview migration without writing files (generates report) |
| `--destructive` | Remove migrated source files after successful migration (interactive prompt if omitted on TTY) |
| `--source <SRC>` | Source folder to scan (e.g., `.claude`). Omit to discover recursively |
| `--max-depth <N>` | Maximum depth for recursive discovery |
| `--manifest` | Generate `aipm.toml` manifests for migrated plugins |
**Detected artifact types:** skills (`SKILL.md`), agents (`*.md` in `agents/`), MCP servers (`.mcp.json`), hooks (`hooks.json`), commands (`commands/*.md`), output styles.
### `aipm install`
Install a plugin from the registry, a git repository, a GitHub shorthand, a local path, or a marketplace.
```
aipm install [OPTIONS] [PACKAGE]
```
| `--locked` | CI mode: fail if lockfile doesn't match manifest |
| `--registry <REG>` | Use a specific registry |
| `--global` | Install globally (available to all projects) |
| `--engine <ENGINE>` | Restrict a global install to a specific engine (e.g., `claude`, `copilot`) |
| `--plugin-cache <POLICY>` | Download cache policy: `auto` (default), `cache-only`, `skip`, `force-refresh`, `no-refresh` |
| `--dir <DIR>` | Project directory (default: `.`) |
**Package spec formats:**
| Registry name | `code-review@^1.0` | Semver range from the default registry |
| `github:` | `github:org/repo:plugin@main` | GitHub repo shorthand |
| `git:` | `git:https://example.com/repo.git:plugin@v1` | Arbitrary git URL |
| `local:` | `local:./path/to/plugin` | Local filesystem path |
| `marketplace:` | `marketplace:my-market:plugin-name` | Named marketplace |
Omit `PACKAGE` to install all dependencies from `aipm.toml`.
**Global installs** write to `~/.aipm/registry/` and are available across all projects. Use `--engine` to scope a plugin to a specific AI tool.
See also: [`docs/guides/global-plugins.md`](docs/guides/global-plugins.md), [`docs/guides/install-git-plugin.md`](docs/guides/install-git-plugin.md), [`docs/guides/cache-management.md`](docs/guides/cache-management.md).
### `aipm update`
Update packages to their latest compatible versions.
```
aipm update [OPTIONS] [PACKAGE]
```
| `--dir <DIR>` | Project directory (default: `.`) |
Omit `PACKAGE` to update all dependencies. Unlike `install`, `update` resolves the latest version within the declared version range and rewrites the lockfile.
### `aipm uninstall`
Remove an installed plugin from the project or the global registry.
```
aipm uninstall [OPTIONS] <PACKAGE>
```
| `--global` | Remove from the global registry |
| `--engine <ENGINE>` | Remove from a specific engine only (global installs) |
| `--dir <DIR>` | Project directory (default: `.`; ignored with `--global`) |
### `aipm link`
Link a local plugin directory for development, overriding the registry version.
```
aipm link [OPTIONS] <PATH>
```
| `--dir <DIR>` | Project directory (default: `.`) |
The plugin at `PATH` shadows the installed version until unlinked. Changes to the local directory are reflected immediately without reinstalling.
### `aipm unlink`
Remove a development link override and restore the registry version.
```
aipm unlink [OPTIONS] <PACKAGE>
```
| `--dir <DIR>` | Project directory (default: `.`) |
### `aipm list`
Show installed plugins or active development link overrides.
```
aipm list [OPTIONS]
```
| `--linked` | Show only active dev link overrides |
| `--global` | Show globally installed plugins |
| `--dir <DIR>` | Project directory (default: `.`) |
### `aipm lint`
Check AI plugin configurations for quality issues across all detected source directories.
```
aipm lint [OPTIONS] [DIR]
```
| `--source <SRC>` | Limit to a specific source type (`.claude`, `.github`, `.ai`) |
| `--reporter <FMT>` | Output format: `human` (default), `json`, `ci-github`, `ci-azure` |
| `--color <MODE>` | Color output: `auto` (default), `always`, `never` |
| `--max-depth <N>` | Maximum directory traversal depth |
Exits with a non-zero status code when violations are found, making it safe to use in CI pipelines. Use `--reporter ci-github` for GitHub Actions annotations or `--reporter ci-azure` for Azure Pipelines.
---
## `aipm-pack` — Author CLI
Scaffolds new plugin packages for publishing.
### `aipm-pack init`
Create a new AI plugin package with manifest and conventional directory layout.
```
aipm-pack init [OPTIONS] [DIR]
```
| `-y, --yes` | Skip interactive prompts |
| `--name <NAME>` | Package name (defaults to directory name) |
| `--type <TYPE>` | Plugin type: `skill`, `agent`, `mcp`, `hook`, `lsp`, `composite` |
Generates an `aipm.toml` manifest and type-appropriate directory structure.
---
## `libaipm` — Core Library
Shared library powering both CLIs. All logic lives here; the binaries are thin wrappers.
### Modules
| `manifest` | Parse, validate, and load `aipm.toml` manifests |
| `manifest::types` | Schema types: `Manifest`, `Package`, `Workspace`, `Components`, `Environment`, `DependencySpec` |
| `manifest::validate` | Name format, semver, dependency version, component path validation |
| `init` | Plugin package scaffolding (`aipm-pack init`) |
| `workspace_init` | Workspace + `.ai/` marketplace scaffolding (`aipm init`) |
| `workspace_init::adaptors` | Tool-specific config writers (Claude Code; Copilot/Cursor planned) |
| `workspace` | Workspace root discovery and `[workspace].members` glob expansion |
| `migrate` | Tool config migration with recursive discovery, dry-run, and all artifact types |
| `lint` | Quality linting for AI plugin configurations, diagnostics, and reporting |
| `discovery` | Gitignore-aware recursive discovery of AI tool source directories (shared by `lint` and `migrate`) |
| `installer` | Package installation pipeline and manifest editing |
| `linker` | Local dev link overrides (`aipm link` / `unlink`) |
| `lockfile` | Deterministic `aipm.lock` creation and drift detection |
| `resolver` | Semver dependency resolution |
| `store` | Content-addressable global package store |
| `registry` | Registry client interface |
| `spec` | Plugin spec parser (`name@version`, `github:`, `git:`, `local:`, `marketplace:` formats) |
| `acquirer` | Local copy and git clone acquisition with source redirect support |
| `cache` | Download cache with 5 policies and per-entry TTL (`~/.aipm/cache/`) |
| `installed` | Global plugin registry with engine scoping and name conflict detection |
| `marketplace` | TOML marketplace manifest parsing (relative, git, and unsupported source types) |
| `engine` | Two-tier engine validation (`aipm.toml` `engines` field + marker file fallback) |
| `platform` | Runtime OS and architecture detection and compatibility checking |
| `path_security` | `ValidatedPath` — rejects traversal, URL-encoded, and absolute paths |
| `locked_file` | OS-level exclusive file locking for cache and registry writes |
| `security` | Configurable source allowlist with CI enforcement |
| `logging` | Layered `tracing` subscriber initialization (stderr verbosity + rotating file log) |
| `frontmatter` | YAML front-matter parsing for plugin files |
| `fs` | Trait-based filesystem abstraction (`Real` + test mocking) |
| `version` | Crate version constant |
### Manifest Format (`aipm.toml`)
```toml
[package]
name = "@company/ci-tools"
version = "1.2.3"
description = "CI automation skills"
type = "composite"
files = ["skills/", "hooks/", "README.md"]
engines = ["claude", "copilot"] # optional — omit to support all engines
[package.source] # optional — marketplace stub redirect
type = "git"
url = "https://github.com/org/repo"
path = "plugins/ci-tools"
[dependencies]
shared-lint = "^1.0"
core-hooks = { workspace = "*" }
heavy-analyzer = { version = "^1.0", optional = true }
# Source dependency formats:
ui-toolkit = { github = "org/repo", path = "plugins/ui", ref = "main" }
local-helper = { path = "../local-helper" }
my-market-dep = { marketplace = "my-registry", name = "dep-name", ref = "v2" }
[features]
default = ["basic"]
basic = []
deep = ["dep:heavy-analyzer"]
[components]
skills = ["skills/lint/SKILL.md"]
agents = ["agents/reviewer.md"]
hooks = ["hooks/hooks.json"]
mcp_servers = [".mcp.json"]
lsp_servers = [".lsp.json"]
scripts = ["scripts/format-code.sh"]
output_styles = ["styles/custom.css"]
settings = ["settings.json"]
[environment]
requires = ["git", "docker"]
aipm = ">=0.5.0"
platforms = ["linux-x64", "macos-arm64", "windows-x64"]
strict = true
[environment.runtime]
node = ">=18.0.0"
[install]
allowed_build_scripts = ["native-tool"]
```
**Plugin types:** `skill` · `agent` · `mcp` · `hook` · `lsp` · `composite`
### Workspace Root Manifest
```toml
[workspace]
members = ["plugins/*"]
plugins_dir = "plugins"
[workspace.dependencies]
common-skill = "^2.0"
[overrides]
"vulnerable-lib" = "^2.0.0"
[catalog]
lint-skill = "^1.5.0"
[catalogs.stable]
framework = "^1.0.0"
[catalogs.next]
framework = "^2.0.0-beta.1"
```
---
## Project Structure
```
crates/
aipm/ Consumer CLI binary (init, install, update, link, unlink, list, lint, migrate)
aipm-pack/ Author CLI binary (init)
libaipm/ Core library (manifest, validation, migration, scaffolding, lint, install, link, resolve)
specs/ Technical design documents
tests/features/ Cucumber BDD feature files (31 files, 300+ scenarios)
research/ Competitive analysis and design research
```
---
## Roadmap
The following features are defined as BDD scenarios and tracked as open issues. They represent the full planned scope beyond what is currently implemented.
### Dependencies
- **Resolution** — semver solver with backtracking, version unification, conflict reporting, overrides ([#1](https://github.com/TheLarkInn/aipm/issues/1))
- **Lockfile** — deterministic `aipm.lock` creation, drift detection, `--locked` CI mode ([#2](https://github.com/TheLarkInn/aipm/issues/2))
- **Features** — default features, opt-out, additive feature unification across the graph ([#3](https://github.com/TheLarkInn/aipm/issues/3))
- **Patching** — `aipm patch` workflow for editing transitive deps without forking ([#4](https://github.com/TheLarkInn/aipm/issues/4))
### Registry
- **Install** — `aipm install` with semver resolution, content-addressable store, integrity verification, strict isolation ([#5](https://github.com/TheLarkInn/aipm/issues/5))
- **Publish** — `aipm-pack pack` / `publish` with `.aipm` archives, dry-run, file allowlist, size limits ([#6](https://github.com/TheLarkInn/aipm/issues/6))
- **Security** — checksums, tamper detection, `aipm audit`, auth, scoped org permissions ([#7](https://github.com/TheLarkInn/aipm/issues/7))
- **Yank** — `aipm-pack yank` / un-yank, deprecation messages ([#8](https://github.com/TheLarkInn/aipm/issues/8))
- **Link** — `aipm link` / `unlink` for local dev overrides ([#9](https://github.com/TheLarkInn/aipm/issues/9))
- **Local + Registry Coexistence** — directory links, gitignore management, vendoring ([#10](https://github.com/TheLarkInn/aipm/issues/10))
### Monorepo
- **Orchestration** — workspace protocol, catalogs, filtering by name/path/changed/dependents, Rush/Turborepo integration ([#11](https://github.com/TheLarkInn/aipm/issues/11))
### Environment
- **Dependencies** — declare required tools, env vars, platforms, MCP runtimes; `aipm doctor` ([#12](https://github.com/TheLarkInn/aipm/issues/12))
- **Host Versioning** — `[environment.hosts]` section for Claude/Copilot/Cursor version constraints ([#54](https://github.com/TheLarkInn/aipm/issues/54))
### Quality & Portability
- **Guardrails** — `aipm lint`, auto-fix, quality scoring on publish ([#13](https://github.com/TheLarkInn/aipm/issues/13))
- **Compositional Reuse** — publish/consume standalone skills, agents, MCP configs, hooks as packages ([#14](https://github.com/TheLarkInn/aipm/issues/14))
- **Cross-Stack** — verified portability across Node.js, .NET, Python, Rust, CMake; offline resolution ([#15](https://github.com/TheLarkInn/aipm/issues/15))
---
## Why not `apm`?
[microsoft/apm](https://github.com/microsoft/apm) (`apm-cli` on PyPI) validates that AI plugin package management is a real problem. However, its architecture falls short for production use across several dimensions:
1. **Runtime dependency.** `apm` requires Python 3.9+ and 13 pip packages. This creates friction for .NET, Rust, Go, and Java teams, and adds version-management overhead. AIPM is a self-contained Rust binary — drop it in any repo regardless of tech stack.
2. **YAML manifest.** `apm.yml` uses YAML, which has the [Norway problem](https://hitchdev.com/strictyaml/why/implicit-typing-removed/) (`3.10` → `3.1`), implicit type coercion (`NO` → `false`), indentation sensitivity, and active security CVEs in parsers. AIPM uses TOML — no coercion, no indentation traps, safe for AI-generated manifests.
3. **No registry.** Packages are git repos. There is no publish lifecycle, no immutable versions, no scoped namespaces, no centralized search, and no way to yank a broken release without deleting git tags. AIPM has a dedicated API registry with publish, yank, scoped packages, and multi-registry routing.
4. **No semver resolution.** `apm` pins by git ref — no `^1.0` ranges, no backtracking, no version unification. Two packages depending on different versions of the same dep each get a full clone. AIPM uses Cargo-model semver with caret/tilde ranges, backtracking, and major-version coexistence.
5. **No integrity verification.** The lockfile records commit SHAs but no file-level hashes. Force-pushes or host compromises silently change what a "version" resolves to. AIPM stores SHA-512 checksums per file and verifies on install.
6. **Full git clones per project.** Every project downloads full copies of every dependency — no deduplication, no global cache. AIPM uses a content-addressable global store (pnpm model) with hard links for 70%+ disk savings.
7. **No dependency isolation.** Everything in `apm_modules/` is accessible to everything else. Phantom dependencies go undetected. AIPM enforces strict isolation — only declared dependencies are accessible.
8. **Minimal security.** No lifecycle script blocking (any package runs arbitrary code), no `audit` command, no principle-of-least-privilege binary split. AIPM blocks scripts by default, ships separate consumer/author binaries, and plans advisory-based auditing.
9. **No transfer format.** Packages are raw git repos — no archive format, no file allowlist, no secrets exclusion. AIPM uses deterministic `.aipm` archives (gzip tar) with sorted files, zeroed timestamps, and default secrets exclusion.
10. **No offline support.** Every install requires network access. AIPM supports `--offline` installation from the global cache.
11. **No CI lockfile mode.** `apm install` uses the lockfile if present, but there is no `--locked` mode that fails on drift. AIPM follows the Cargo model: `install` never upgrades, `update` explicitly resolves latest, `--locked` fails on any mismatch.
12. **No workspace features.** No workspace protocol, no catalogs, no dependency inheritance, no filtering. AIPM supports all of these for monorepo-scale plugin management.
13. **Compilation coupling.** `apm` tightly couples package management with `AGENTS.md` / `CLAUDE.md` generation. AIPM decouples packaging from host discovery — AI tools discover plugins naturally via directory scanning.
In short: `apm` is a useful prototype that proves the problem space. AIPM is designed to be the production-grade infrastructure for it.
---
## Contributing
Contributions and suggestions are welcome! Please open an issue or pull request on [GitHub](https://github.com/thelarkinn/aipm).
## License
This project is licensed under the [MIT License](LICENSE).