ai-adapter

Common management infrastructure CLI tool for AI agent scripts

A CLI tool for managing AI agent instruction files (.github/instructions etc.) and scripts in groups. Easily share and migrate settings across environments.

Features

• Centralized Management: All data is consolidated under ~/.ai-adapter/. Centrally manage settings across projects
• Environment Switching: Switch agent settings and scripts per environment (e.g., work, home)
• GitHub Sync: Use ai-adapter sync to sync ~/.ai-adapter/ with a GitHub remote. Easy team sharing and PC migration
• Agent Binding: Bind agent names to environments for automatic resolution based on context
• Skill Management: Manage and deploy skills in SKILL.md format (.github/skills/)
• Command Management: Manage and deploy VS Code custom command definitions (.github/commands/)
• Prompt Management: Manage and deploy prompt templates for AI agents (.github/prompts/)
• MCP Server Management: Centrally manage MCP server settings and output in each tool format
• OpenCode Integration: Generate opencode.json with MCP, skills, prompts, and agents; symlink .opencode → .github
• OpenClaw Integration: Export MCP servers and skills to OpenClaw format (--format openclaw)
• Codex CLI Integration: Generate AGENTS.md for OpenAI Codex CLI (ai-adapter codex install)
• Root-Level Agent Management: Manage AGENTS.md, CLAUDE.md, etc. as first-class artifacts, deployable to project root

Installation

Prerequisites

• Python 3.10+
• uv (package management)

# Also installable via pip
pip install ai-adapter

# Or use uv
uv pip install ai-adapter

Upgrade

# Upgrade via pip
pip install --upgrade ai-adapter

# Upgrade via uv
uv pip install --upgrade ai-adapter

# Upgrade to the latest development version
cd ai-adapter && git pull && uv sync && uv pip install -e .

Development Version

git clone <repository-url>
cd ai-adapter
uv sync
uv pip install -e .

Verification

ai-adapter --help
ai-adapter --version

Quick Start

# 1. Initialize
ai-adapter init

# 2. Add an agent file (for .github/agents/, e.g. individual .agent.md files)
ai-adapter sub-agent add ~/my-agents/reviewer.md

# 2b. Add a root-level agent file (for project-root AGENTS.md/CLAUDE.md)
ai-adapter agent add ~/my-agents/AGENTS.md

# 3. Add an environment
ai-adapter env add myhome

# 4. Add a script
ai-adapter bin add --env myhome ~/scripts/deploy.sh

# 5. Add a skill
ai-adapter skill add ~/my-skills/database-schema

# 6. Add an MCP server
ai-adapter mcp add github --command npx --args @modelcontextprotocol/server-github

# 7. Deploy to a project
cd your-project
ai-adapter sub-agent get reviewer      # → .github/agents/reviewer.md
ai-adapter agent get AGENTS            # → ./AGENTS.md (project root)
ai-adapter bin get --env myhome deploy   # → .github/bin/deploy.sh
ai-adapter skill get database-schema  # → .github/skills/database-schema/
ai-adapter mcp get                     # → .mcp.json

# 8. Deploy to OpenClaw (optional, requires OpenClaw installed)
ai-adapter mcp get --format openclaw          # → ~/.openclaw/openclaw.json
ai-adapter skill get-all --format openclaw    # → ~/.openclaw/skills/

# 9. Sync with GitHub (share settings)
ai-adapter sync

Command Reference

ai-adapter start <URL>

One-click setup of ~/.ai-adapter/ by linking with a GitHub remote repository. Attempts to clone, and if that fails, initializes as a new repository.

# Setup from a new or existing repository
ai-adapter start git@github.com:user/my-agent-config.git

ai-adapter init

Initializes the ~/.ai-adapter/ directory and configuration file (creates agents/, bin/, skills/, commands/, prompts/, instructions/, mcp/ directories). You can set a remote repository via the --remote option or an interactive prompt.

# Minimal initialization (remote can be set later)
ai-adapter init

# Initialize with a remote specified
ai-adapter init --remote git@github.com:user/my-agent-config.git

ai-adapter status

Displays the current status (registration counts, default environment, etc.).

ai-adapter status

ai-adapter add-all-rec

Batch-registers all files under .github/ and .mcp.json into ~/.ai-adapter/. Also discovers root-level files (AGENTS.md, AGENT.md, CLAUDE.md, copilot-instructions.md) and registers them into ~/.ai-adapter/instructions/. Run this after cloning a synced repository to automatically restore configuration from files.

# Run from the project root
ai-adapter add-all-rec

ai-adapter get-all-rec

Deploys all registered items across all categories to .github/ at once. The reverse of add-all-rec — runs sub-agent get-all + bin get-all + skill get-all + command get-all + prompt get-all + agent get-all (root instructions) + mcp get in a single command.

# Deploy everything from ~/.ai-adapter/ to the current project
ai-adapter get-all-rec

# Force overwrite to a specific project
ai-adapter get-all-rec --force --project-dir /path/to/project

ai-adapter agent

Manages root-level agent instruction files (AGENTS.md, CLAUDE.md, copilot-instructions.md). Deploys to project root (./).

ai-adapter agent add ~/my-agents/AGENTS.md
ai-adapter agent list
ai-adapter agent get AGENTS          # → ./AGENTS.md
ai-adapter agent get CLAUDE          # → ./CLAUDE.md
ai-adapter agent remove AGENTS
ai-adapter agent remove-all --force

ai-adapter sub-agent

Manages .agent.md files (for VS Code / GitHub Copilot agent definitions). Deploys to .github/agents/.

ai-adapter sub-agent add ~/dotfiles/agents/reviewer.md
ai-adapter sub-agent list
ai-adapter sub-agent get reviewer
ai-adapter sub-agent remove reviewer
ai-adapter sub-agent remove-all --force

ai-adapter env

Manages environment settings.

ai-adapter env add office
ai-adapter env list
ai-adapter env set-default office
ai-adapter env link-agent reviewer office
ai-adapter env remove-all --force

ai-adapter bin

Manages script files. [env] is optional; if omitted, environment resolution logic applies.

ai-adapter bin add --env myhome ~/scripts/deploy.sh
ai-adapter bin list
ai-adapter bin get deploy
ai-adapter bin remove deploy
ai-adapter bin remove-all --force

The --env flag is optional; when omitted, environment resolution logic applies.

ai-adapter skill

Manages skills (directories containing SKILL.md).

ai-adapter skill add ~/skills/database-schema/
ai-adapter skill list
ai-adapter skill get database-schema
ai-adapter skill search prisma
ai-adapter skill link-agent database-schema reviewer

ai-adapter mcp

Manages MCP server settings.

# Interactive addition
ai-adapter mcp add github --command npx --args @modelcontextprotocol/server-github

# Batch-import from .mcp.json
echo '{"mcpServers":{"github":{"command":"npx","args":["@modelcontextprotocol/server-github"]}}}' > .mcp.json
ai-adapter mcp add --file .mcp.json

# List
ai-adapter mcp list

# Export to current directory (standard format)
ai-adapter mcp get
# Export to a specified directory
ai-adapter mcp get --path /path/to/project
# Export to OpenClaw format (~/.openclaw/openclaw.json)
ai-adapter mcp get --format openclaw
# Export to OpenClaw format with custom path (no merge, new file)
ai-adapter mcp get --format openclaw --path /path/to/output

ai-adapter command

Manages VS Code custom command definitions (.sh, .py, .js, etc.).

ai-adapter command add ~/scripts/deploy.sh
ai-adapter command list
ai-adapter command get deploy
ai-adapter command remove deploy
ai-adapter command remove-all --force

ai-adapter prompt

Manages prompt templates for AI agents.

ai-adapter prompt add ~/prompts/code-review.md
ai-adapter prompt list
ai-adapter prompt get code-review
ai-adapter prompt remove code-review
ai-adapter prompt remove-all --force

ai-adapter opencode

Manages OpenCode integration settings.

# Create an alias from .opencode to .github
ai-adapter opencode alias

# Generate an opencode.json with MCP servers, skills, and agents
ai-adapter opencode install

# Remove
ai-adapter opencode uninstall

# Validate and fix agent files
ai-adapter opencode validate
ai-adapter opencode validate --fix

ai-adapter codex

Manages Codex CLI integration. Generates AGENTS.md in plain Markdown for OpenAI Codex CLI.

# Generate AGENTS.md for Codex CLI
ai-adapter codex install

# Force overwrite
ai-adapter codex install --force

# Remove
ai-adapter codex uninstall

OpenClaw Integration

ai-adapter can export configurations to OpenClaw (a personal AI assistant with multi-channel gateway) using the --format openclaw option on existing commands.

# Export MCP servers to OpenClaw format
ai-adapter mcp get --format openclaw

# Export MCP servers to a custom location (new file, no merge)
ai-adapter mcp get --format openclaw --path /path/to/output

# Deploy all skills to OpenClaw
ai-adapter skill get-all --format openclaw --force

Key design principles:

• ${VAR} format for env values — resolved by OpenClaw at load time from ~/.openclaw/.env
• Server-name-based merge — existing non-ai-adapter MCP servers in openclaw.json are preserved
• .bak backup — existing openclaw.json is backed up before modification
• No format conversion needed for skills — both tools use SKILL.md with YAML frontmatter

ai-adapter bin add-path

Outputs and applies shell configuration to add the current project's .github/bin/ to PATH. This allows you to run .github/bin/add_task.sh directly as add_task.sh.

# Interactively select a shell configuration file
ai-adapter bin add-path

# Write directly to zshrc
ai-adapter bin add-path --shell zshrc
ai-adapter bin add-path --shell bash_profile

ai-adapter uninstall

Removes ~/.ai-adapter/ and restores the initial state.

ai-adapter uninstall
ai-adapter uninstall --force
ai-adapter uninstall --keep-git

ai-adapter sync

Syncs ~/.ai-adapter/ with a GitHub remote.

ai-adapter sync

Internally, the following steps are executed:

1. Check Git repository (run git init if uninitialized)
2. git add -A && git commit
3. git pull --rebase origin main
4. git push origin main

Data Storage

All data is stored under ~/.ai-adapter/.
Project-level files are deployed to .github/ (may change in future versions).

~/.ai-adapter/
├── config.json                 # Main configuration file
├── agents/                     # AI agent .agent.md files (managed by sub-agent)
│   ├── reviewer.md
│   ├── implementer.md
│   └── researcher.md
├── bin/                        # Script files
│   ├── deploy-prod.sh
│   └── deploy-staging.sh
├── skills/                     # Skill directories
│   ├── database-schema/
│   │   ├── SKILL.md
│   │   └── examples/
│   └── security-review/
│       └── SKILL.md
├── instructions/               # Root-level agent files (managed by agent)
│   ├── AGENTS.md
│   └── CLAUDE.md
└── mcp/                        # MCP server settings
    └── servers.json

This directory can be turned into a Git repository and synced across multiple PCs via GitHub.

Environment Resolution Priority

When [env] is omitted in bin commands:

1. If the --agent option is explicitly specified, the bound environment of that agent is used
2. If the relevant agent exists in agent_bindings, its bound environment is used
3. If neither applies, default_env (default: "default") is used

Configuration File

All settings are stored in ~/.ai-adapter/config.json.

{
  "version": 1,
  "default_env": "default",
  "agent_bindings": [
    { "agent": "reviewer", "env": "myhome" },
    { "agent": "implementer", "env": "office" }
  ],
  "agents": [
    { "name": "reviewer", "description": "Agent for code review" },
    { "name": "implementer", "description": "Agent for implementation" }
  ],
  "envs": [
    { "name": "default", "description": "Default environment" },
    { "name": "myhome", "description": "Home development environment" },
    { "name": "office", "description": "Office development environment" }
  ],
  "bins": [
    { "name": "deploy-prod.sh", "env": "myhome", "description": "Production deployment" },
    { "name": "format-all.sh", "env": "default", "description": "Code formatting" }
  ],
  "skills": [
    {
      "name": "database-schema",
      "description": "Database schema design and review knowledge",
      "path": "skills/database-schema",
      "tags": ["database", "prisma", "schema"],
      "agent": "reviewer"
    }
  ],
  "mcp_servers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env_keys": ["GITHUB_TOKEN"],
      "enabled": true,
      "tools": ["vscode", "claude", "cursor"]
    }
  ]
}

Use Cases

Sharing LLM configuration files between office and home

# Office PC
ai-adapter init
ai-adapter agent add ~/company-agent.md
ai-adapter env add office
ai-adapter sync

# Home PC
git clone <your-ai-adapter-repo> ~/.ai-adapter
ai-adapter agent get company-agent   # → .github/agents/company-agent.md

Migrating to a new PC

# New PC
git clone <your-ai-adapter-repo> ~/.ai-adapter
ai-adapter bin list                  # Check registered scripts
ai-adapter bin get deploy-prod       # Deploy the required scripts

Different agent settings per project

ai-adapter env add project-a
ai-adapter env add project-b
ai-adapter agent add reviewer-a.md
ai-adapter env link-agent reviewer-a project-a

# Running in project-a automatically uses the project-a environment
cd /path/to/project-a
ai-adapter bin add deploy.sh

Development

Development Environment

uv sync
uv pip install -e .

Running Tests

# All tests
uv run python -m unittest discover tests

# Specific file
uv run python -m unittest tests/test_env.py

# Verbose output
uv run python -m unittest discover tests -v

Linter and Type Checking

uv run ruff check .
uv run ruff format .
uv run mypy src/

Project Structure

ai-adapter/
├── pyproject.toml              # Project settings, dependencies, entry points
├── README.md                   # This file
├── LICENSE                     # MIT License
├── .gitignore                  # Git ignore settings
├── src/
│   └── ai_adapter/
│       ├── __init__.py         # Version information
│       ├── __main__.py         # python -m ai_adapter support
│       ├── cli.py              # CLI entry point (registers all subcommands)
│       ├── config.py           # Read/write ~/.ai-adapter/config.json
│       ├── models.py           # Data models (dataclass)
│       ├── diff.py             # Sync diff comparison
│       ├── git.py              # Git operation wrapper
│       ├── sync.py             # sync command (GitHub sync)
│       ├── agent_format.py     # Agent file YAML format utilities
│       ├── commands/           # Subcommand implementations
│       │   ├── agent.py        # agent subcommand
│       │   ├── bin.py          # bin subcommand
│       │   ├── command.py      # command subcommand
│       │   ├── env.py          # env subcommand
│       │   ├── mcp.py          # mcp subcommand
│       │   ├── prompt.py       # prompt subcommand
│       │   └── skill.py        # skill subcommand
│       └── providers/          # External tool integrations
│           ├── opencode.py     # OpenCode integration (install/alias/uninstall)
│           ├── openclaw.py     # OpenClaw integration (MCP + skills export)
│           └── codex.py        # Codex CLI integration (AGENTS.md generation)
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_agent.py
│   ├── test_env.py
│   ├── test_bin.py
│   ├── test_skill.py
│   ├── test_mcp.py
│   ├── test_sync.py
│   ├── test_git.py
│   ├── test_cli.py
│   └── test_instruction.py
└── examples/
    └── sample-config.json      # Sample configuration file

Tech Stack

License

MIT License