# mai
**AI Tooling Package Manager** — Manage skills, commands, and MCP connectors for AI agents.
## Quick Start
```bash
# Build
cargo build --release
cp target/release/mai ~/.local/bin/
# Switch AI tool
mai use qwen
# Install packs (local by default)
mai install aif
mai install mcp/postgres
# Install globally (user-wide)
mai install -g aif
# List packs
mai list
```
## Commands
| `mai use <tool>` | Switch active AI tool |
| `mai install <pack>` | Install pack (skill/command/mcp) |
| `mai install -g <pack>` | Install pack globally (user-wide) |
| `mai list` | List installed packs |
| `mai list --global` | List only global packs |
| `mai list --local` | List only local packs |
| `mai init` | Initialize a new mai project |
| `mai sync` | Sync project packs with registry |
| `mai check` | Verify lock file integrity |
| `mai remove <pack>` | Remove pack |
| `mai remove -g <pack>` | Remove global pack |
| `mai update <pack>` | Update pack |
| `mai update -g <pack>` | Update global pack |
| `mai completions` | Shell completions |
**Pack format**: `[type/]name[@version]`
Example: `skill/aif@1.0.0`, `mcp/postgres`, `latest`
## Installation Scopes
mai supports two installation scopes, similar to how `cargo` handles dependencies:
### Local Installation (Default)
Local installations are project-specific. Packs are stored in the `.mai/` directory within your project root.
```bash
# Install locally (default)
mai install aif
# Creates:
# .mai/
# ├── config/
# │ └── config.toml
# ├── packs/
# │ └── qwen/
# │ └── aif/
# │ └── 1.0.0/
# └── cache/
```
Local installations are ideal for:
- Project-specific AI tools and skills
- Team-shared configurations (commit `.mai/` to version control)
- Isolating dependencies per project
### Global Installation
Global installations are user-wide. Packs are stored in XDG directories (or fallback to `~/.mai/`).
```bash
# Install globally
mai install -g aif
# Creates (on Linux with XDG):
# ~/.config/mai/config.toml
# ~/.local/share/mai/packs/
# ~/.cache/mai/
# Or fallback (if XDG not available):
# ~/.mai/
# ├── config/
# ├── packs/
# └── cache/
```
Global installations are ideal for:
- Commonly used skills across all projects
- Personal AI tooling preferences
- System-wide MCP connectors
### Pack Resolution Order
When resolving packs, mai checks in this order:
1. **Local** (`.mai/packs/`) — takes priority
2. **Global** (`~/.local/share/mai/packs/` or XDG equivalent)
This allows you to override global packs with project-specific versions.
## What is a Pack?
A **pack** (package) is a collection of AI tools and utilities. A pack can contain:
- **Skills** — AI agent capabilities and behaviors
- **Commands** — CLI tools for AI assistants
- **MCPs** — Model Context Protocol connectors
Packs are **tool-specific**, meaning they must be installed separately for each AI tool (Qwen, Claude, Cursor, etc.). Use `mai use <tool>` to switch between tools and configure them independently.
## Configuration
### Directories
**Global (XDG):**
```
~/.config/mai/ # Config (config.toml)
~/.local/share/mai/ # Pack storage
~/.cache/mai/ # Cache
```
**Fallback (if XDG not available):**
```
~/.mai/ # All data in one location
```
**Local (per project):**
```
.mai/ # Project root
├── config/
│ └── config.toml
├── packs/
│ └── <tool>/
│ └── <pack>/
│ └── <version>/
└── cache/
```
### Project Files
**mai.toml** — Project manifest:
```toml
[project]
name = "my-ai-project"
[[dependencies]]
tool = "qwen"
name = "aif"
type = "skill"
version = "^1.0.0"
[[dependencies]]
tool = "qwen"
name = "postgres"
type = "mcp"
version = "latest"
```
**mai.lock** — Pinned versions (auto-generated).
## Development
```bash
cargo build
cargo test
cargo clippy -- -D warnings
```
Logging: `LOG_LEVEL=debug cargo run -- list`
## Documentation
| [Getting Started](docs/getting-started.md) | Quick start tutorial |
| [CLI Reference](docs/cli-reference.md) | Complete command docs |
| [Project Config](docs/project-config.md) | `mai.toml` and `mai.lock` |
| [Versioning](docs/versioning.md) | Semver and version ranges |
## License
MIT