Metadata-Version: 2.4
Name: ai-config-cli
Version: 0.3.0
Summary: Declarative plugin manager for Claude Code
Project-URL: Homepage, https://github.com/safurrier/ai-config
Project-URL: Documentation, https://safurrier.github.io/ai-config/
Project-URL: Repository, https://github.com/safurrier/ai-config
Project-URL: Issues, https://github.com/safurrier/ai-config/issues
Project-URL: Changelog, https://github.com/safurrier/ai-config/blob/main/CHANGELOG.md
Author-email: Alex Furrier <afurrier@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,configuration,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=1.0.0; python_full_version < '3.11'
Requires-Dist: watchdog>=3.0
Provides-Extra: dev
Requires-Dist: docker>=7.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.1.1; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: ty>=0.0.2; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: types-requests>=2.28; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.6.14; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26.1; extra == 'docs'
Description-Content-Type: text/markdown

# ai-config

Declarative plugin manager for Claude Code.

(Future: Codex CLI and OpenCode support planned once plugins become more standardized for sharing ai-context)

## Why this exists

Claude Code plugins are useful. They let you extend Claude with custom skills, hooks, and MCP servers. The problem is managing them.

Without ai-config, you're running `claude plugin install` and `claude plugin marketplace add` commands by hand across machines. There's no config file. No way to version control your setup. No way to share it.

ai-config fixes that. You write a YAML file describing what plugins you want, and it handles the rest.

Or more simply, run `ai-config init` and it writes the config for you.

## 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
- Integration with 47 different tools (we integrate with one)
- 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.

## Installation

> **Alpha software**: This project is in active development. APIs and config formats may change between versions.

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

This installs `ai-config` globally. Run `ai-config --help` to verify.

### From source (latest)

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

### For development

```bash
git clone https://github.com/safurrier/ai-config.git
cd ai-config
just setup    # Install dependencies
just check    # Run lint, type check, tests
```

## Quick Start

**1. Create your config**

```bash
ai-config init
```

Interactive wizard walks you through adding marketplaces and plugins. Creates `.ai-config/config.yaml`.

**2. Sync to install plugins**

```bash
ai-config sync
```

Installs/uninstalls plugins to match your config. Run this after editing `config.yaml`.

If plugins seem stale or out of date:

```bash
ai-config sync --fresh
```

**3. Iterate with watch (plugin development)**

```bash
ai-config watch
```

Auto-syncs when you edit config or plugin files. Press Ctrl+C to stop.

**Note:** Claude Code loads plugins at session start. After changes sync, restart Claude Code to apply them. Use `claude --resume` to continue your previous session.

**4. Troubleshoot with doctor**

```bash
ai-config doctor
```

Validates marketplaces, plugins, skills, hooks, and MCP servers. Shows fix hints for any issues.

## What it does

**Declarative config** - Define your plugins in `.ai-config/config.yaml`:

```yaml
version: 1
targets:
  - type: claude
    config:
      marketplaces:
        claude-code-tutorial:
          source: github
          repo: safurrier/claude-code-tutorial
      plugins:
        - id: claude-code-tutorial@claude-code-tutorial
          scope: user
          enabled: true
```

**Interactive setup** - Don't want to write YAML? Run the wizard:

```bash
ai-config init
```

It walks you through adding marketplaces and plugins with arrow-key navigation.

**Sync** - Make reality match your config:

```bash
ai-config sync
```

**Validation** - Find problems before they bite you:

```bash
ai-config doctor
```

Checks that marketplaces exist, plugins are installed, skills are valid, hooks work.

## Commands

| Command | What it does |
|---------|--------------|
| `init` | Interactive config generator |
| `sync` | Install/uninstall plugins to match config |
| `status` | Show what's currently installed |
| `watch` | Auto-sync on file changes (plugin development) |
| `update` | Update plugins to latest versions |
| `doctor` | Validate setup and show fix hints |
| `plugin create` | Scaffold a new plugin |
| `cache clear` | Clear the plugin cache |

## Config file locations

ai-config looks for config in this order:

1. `.ai-config/config.yaml` (project-local)
2. `~/.ai-config/config.yaml` (global)

You can also pass `-c /path/to/config.yaml` to any command.

## Scopes

Plugins can be installed in different scopes:

- **user** - Available everywhere (`~/.claude/plugins/`)
- **project** - Only in the current project (`.claude/plugins/`)

## Troubleshooting

**Plugin installed but not showing up in / commands**

Clear cache and re-sync:

```bash
ai-config sync --fresh
```

**Something's broken and Claude Code won't help**

```bash
ai-config doctor --verbose
```

## License

MIT
