ai-config

Declarative plugin manager for Claude Code — with cross-tool conversion to Codex, Cursor, OpenCode, and Pi.

Why this exists

You've spent time building up your AI coding setup: custom skills, MCP servers, hooks, workflows. Then you want to try Codex or Pi, and you're starting from scratch. Or you get a new machine and have to remember what you installed.

ai-config solves both problems. You define your setup in one YAML file, then use it to:

1. Install your Claude Code plugins reproducibly across machines with ai-config sync.
2. Convert those plugins for other tools — same skills, same config, less manual porting.

No more vendor lock-in because your customizations are trapped in one tool's config directory. No more hand-maintaining Claude plugins, Codex packages, Cursor/OpenCode config, and Pi extensions.

Or more simply: run ai-config init and it walks you through the config.

What this isn't

This README does not have:

• 14 shields.io badges declaring build status, coverage, npm downloads, discord members, twitter followers, and mass-to-charge ratio
• A mass of emojis to make it look "friendly" and "approachable"
• Claims about revolutionizing your development workflow
• A "Quick Start" that's actually 73 steps
• Screenshots of a dashboard that doesn't exist
• A "Powered by AI" badge despite just being a for-loop

It's a config file and some commands. That's it.

Install

pip install ai-config-cli
# or
uv tool install ai-config-cli

This installs the ai-config command. Check that it resolves before changing any tool config:

ai-config --help

From source, use the repo URL instead:

uv tool install git+https://github.com/safurrier/ai-config

Quick start: preview before you sync

1. Create a config

ai-config init

The wizard adds marketplaces and plugins, then writes .ai-config/config.yaml unless you pass -o. If the wizard offers to run sync immediately, say no when you want to inspect the file first.

2. Preview the changes

ai-config sync --dry-run

This is the safe checkpoint. It shows what would be installed, removed, or converted without writing plugin output.

3. Apply the sync

ai-config sync --verify

This makes installed plugins match your config and verifies the result. If your config enables conversion, sync also writes target-tool output for Codex, Cursor, OpenCode, and Pi according to your conversion scope.

4. Check for problems

ai-config doctor

Claude Code loads plugins at session start. After sync changes plugins, restart Claude Code to apply them. Use claude --resume if you want to continue the previous session.

What sync does

A config can install Claude Code plugins and convert them for other tools:

version: 1
targets:
  - type: claude
    config:
      marketplaces:
        my-plugins:
          source: github
          repo: myorg/ai-plugins
      plugins:
        - id: code-review@my-plugins
          scope: user
      conversion:
        enabled: true
        targets: [codex, cursor, opencode, pi]
        scope: user

With conversion enabled, ai-config sync can write outputs such as:

• Claude Code: plugins installed through Claude Code's plugin system
• Codex: installable plugin packages and ai-config-owned local marketplaces under .ai-config/codex/; sync manages them through codex plugin
• Cursor: skills, commands, hooks, and MCP config under .cursor/ or ~/.cursor/
• OpenCode: skills plus opencode.json / opencode.lsp.json
• Pi: skills, prompt templates, and hook extensions under .pi/ or ~/.pi/

The exact paths depend on conversion scope and output_dir. Codex 0.6.0 is a breaking migration from loose .codex output; review the Codex migration guide before syncing. See Configuration and Conversion for full rules.

Config lookup

By default, commands look for config in this order:

1. .ai-config/config.yaml
2. .ai-config/config.yml
3. ~/.ai-config/config.yaml
4. ~/.ai-config/config.yml

Project-local config wins over global config. Pass -c /path/to/config.yaml to use a specific file.

Relative local marketplace paths and conversion output paths are resolved from the config's project root. Environment variables and ~ are expanded at load time, so paths like $DOTS_REPO/plugins can stay portable in dotfiles.

Common workflows

For options and examples, use Commands. For target behavior and fidelity notes, use Conversion.

Development

git clone https://github.com/safurrier/ai-config.git
cd ai-config
uv sync --all-extras
uv run ruff check src/
uv run ty check src/
uv run pytest tests/unit/ -v

If you use just, the shortcut is:

just setup
just check

Troubleshooting

DO preview first, NOT blind sync, BECAUSE sync can install/uninstall plugins and write converted tool config.

ai-config sync --dry-run

DO use --fresh when cached plugins or converted output look stale, NOT hand-delete random target files first, BECAUSE sync knows the cache and conversion state.

ai-config sync --fresh

DO validate converted output with target doctor, NOT assume every Claude feature maps 1:1, BECAUSE some hooks, MCP settings, commands, and agents degrade or skip depending on the target.

ai-config doctor --target all ./output-dir

Further reading

• Commands — complete CLI reference
• Configuration — config schema, path resolution, scopes, and examples
• Conversion — target mappings, dry runs, reports, and validation

License

MIT