mai

AI Tooling Package Manager — Manage skills, commands, and MCP connectors for AI agents.

Quick Start

# 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

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.

# 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/).

# 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:

[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

cargo build
cargo test
cargo clippy -- -D warnings

Logging: LOG_LEVEL=debug cargo run -- list

Documentation

License

MIT