airc

AI Config Manager - A TypeScript-based CLI tool to manage and install AI tool configuration files across multiple AI development tools.

Idea is manage your AI tools config in same place and then reuse everywhere.

Installation

npm install airc-cli -g
airc --help

# Or use npx directly
npx airc-cli --help

Quick Start

1. Initialize airc

Initialize your local config directory:

airc init

This creates:

• ~/.airc/ - User config directory
• ~/.airc/config/skills/ - Local skills config storage
• ~/.airc/config/commands/ - Local commands config storage
• ~/.airc/config/agents/ - Local commands config storage
• ~/.airc/config/mcp-config.json - MCP server configurations
• ~/.aircrc - Configuration file for airc cli

2. Add a Source

Add a git repository containing AI configs. This automatically copies config files to your local directory:

# Add from GitHub (full repository)
airc source add https://github.com/vercel-labs/agent-skills

# Add with custom name
airc source add https://github.com/vercel-labs/agent-skills --name vercel-skills

# Add from GitHub tree URL
airc source add https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices

What happens:

• Repository is cloned to ~/.airc/temp/
• Config folders (skills, commands, agents) are automatically discovered
• Config files are copied to ~/.airc/config/{type}/{source-name}/
• Metadata is tracked in ~/.aircrc for smart updates
• Remove temp repo

3. View Your Configs

List all configs in your local directory:

# List all configs
airc list

# Filter by type
airc list --type skills

4. Install to AI Tools

Install your configs to specific AI tools:

# Install to Claude for your project only(<project-root>/.claude)
cd <project-root>
airc install claude

# Install globally(~/.claude)
airc install claude --global

4. Update imported config

airc source update react-best-practices

5. Removing Unwanted Configs

airc remove react-best-practices

6. Add your own configs

Initially we have three folders in config folder(skills / commands / agents), but you can add your own custom folder, they will be copied to target folder when using airc install command:

airc/
├── config/           # Default configuration files
│   ├── commands/     # Command definitions
│   ├── skills/       # Skill definitions
│   ├── agents/       # Agent definitions
│   └── scripts/      # Add your own config folder

Managing MCPs (Model Context Protocol)

airc now supports managing MCP (Model Context Protocol) server configurations. MCPs allow AI tools to interact with external systems and services through standardized server interfaces.

MCP Config Structure

MCP configurations are stored in ~/.airc/config/mcp-config.json:

{
  "filesystem": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users"]
  },
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
    }
  }
}

Field Descriptions:

• type: Protocol type (currently only "stdio" is supported)
• command: The command to run the MCP server (e.g., "npx", "node")
• args: Array of command arguments (optional)
• env: Environment variables for the server (optional)

Viewing MCPs

List all available MCPs along with your other configs:

airc list

Example output:

📋 Your Configs

📦 Commands (2)
✏️  manual commit
✏️  manual push

📦 MCP Configs (2)
✏️  manual filesystem
       type: stdio
✏️  manual github
       type: stdio

Total: 4 configs
  0 imported, 4 manual

Installing MCPs to AI Tools

When you run airc install <tool>, you'll be prompted to select which MCPs to install:

# Install to Claude (project-level)
cd <project-root>
airc install claude

# Install globally
airc install claude --global

Interactive MCP selection:

📦 MCP Configs
? Select MCPs to install: (Press <space> to select, <a> to toggle all)
❯◯ filesystem (stdio)
 ◯ github (stdio)

After selection, MCPs are merged into the tool's config file:

✅ Successfully installed 2 MCP configs
   Installed to: .mcp.json

Handling MCP Conflicts

If an MCP with the same name already exists in the tool's config, use the --force flag to overwrite:

airc install claude --force

Without --force:

❌ Error: MCP conflicts detected: filesystem, github
   These MCPs already exist in the config file.
   Use --force to overwrite existing MCPs.

With --force:

✅ Successfully installed 2 MCP configs (overwrote 2 existing)

Removing MCPs

Remove an MCP from your local configuration:

airc remove <mcp-name> --force

Example:

airc remove github --force

Output:

🗑️  Remove Config

MCP Config: github
Type: stdio
Source: manual (MCP configuration)

✅ Successfully removed MCP "github"
   MCP removed from ~/.airc/config/mcp-config.json

Tool-Specific MCP Support

Different AI tools store MCPs in different locations with different field names:

| Tool | Project Mode Path | Global Mode Path | Field Name | |------|------------------|------------------|------------| | Claude | .mcp.json | ~/.claude.json | mcpServers | | Gemini | .gemini/settings.json | ~/.gemini/settings.json | mcpServers | | Antigravity | N/A (global only) | ~/.gemini/antigravity/mcp_config.json | mcpServers | | Cursor | .cursor/mcp.json | ~/.cursor/mcp.json | mcpServers | | Copilot | .copilot/mcp-config.json | ~/.copilot/mcp-config.json | mcpServers | | OpenCode | opencode.json | ~/.config/opencode/opencode.json | mcp |

Note: Antigravity only supports global mode. When installing to Antigravity in project mode, you'll see an informational message:

ℹ️  Note: Antigravity only supports global MCP installation
   Use --global flag to install MCPs for Antigravity

Troubleshooting

MCPs not showing in airc list:

• Ensure ~/.airc/config/mcp-config.json exists and contains valid JSON
• Check file permissions on the mcp-config.json file

MCP installation fails:

• Verify the tool supports MCP format (see table above)
• For Antigravity, use --global flag
• Check that the target config file has write permissions
• Use --force flag if MCPs already exist and you want to overwrite

MCPs not working after installation:

• Verify the MCP server command is correctly installed (e.g., npx @modelcontextprotocol/server-filesystem)
• Check environment variables are set correctly in the MCP config
• Restart your AI tool after installing MCPs
• Consult the specific AI tool's documentation for MCP troubleshooting