npm package: @nolbuk/miau
Description: AI Configuration Manager CLI - Manage AI tool configurations globally and per-project
Author: nolbuk
Latest version: 0.3.8

# miau

One config, every AI tool. Define skills, agents, commands and MCP servers once — sync them to Claude Code, OpenCode, Gemini CLI, Copilot and Cursor.

## Install

```bash
npm install -g @nolbuk/miau
```

Node.js >= 20 required.

## Getting Started

```bash
miau          # interactive wizard
miau init     # setup global config + link AI tools
```

## How It Works

```
~/.miau/config/          your project repo
  skills/                  .ai/
  agents/         miau       skills/    (copied)
  commands/      ----->      agents/    (copied)
  mcp/                       commands/  (copied)
    servers.yaml             mcp/       (copied)
  providers/                 config.json
```

`miau init` links your global config to each AI tool. `miau project init` copies selected resources into the project's `.ai/` directory. `miau sync` regenerates provider-specific files.

Override the default config path with `MIAU_CONFIG`:

```bash
export MIAU_CONFIG=~/my-configs/miau
```

## Creating Resources

After running `miau init`, populate your global config with skills, agents, commands, and MCP servers. Below are examples of each.

### Skill

A skill is a markdown file with frontmatter. Place it at `~/.miau/config/skills/{name}.md` or `~/.miau/config/skills/{name}/SKILL.md` (for skills with extra assets).

```markdown
---
name: search
description: "Fast codebase exploration subagent"
---

# Search Agent

Fast, lightweight subagent for codebase exploration and search.

## Responsibilities

- Find files by patterns (glob)
- Search code for keywords (grep)
- Locate specific functions, classes, or patterns
```

### Agent

An agent lives at `~/.miau/config/agents/{name}/AGENT.md`. The key difference from skills is the `tools` field, which defines what the agent can do.

```markdown
---
name: search
description: Fast codebase exploration subagent
tools: Glob,Grep,Read
model: inherit
---

# Search Agent

Find files by patterns and search code for keywords.

## When to Use

- Find files matching a pattern (e.g., `**/*.service.ts`)
- Search for specific code patterns
- Quickly locate where something is defined
```

### Command

A command lives at `~/.miau/config/commands/{name}/COMMAND.md`. Commands can receive parameters and are invoked via `/name` in supported tools.

```markdown
---
name: changelog
description: Create a changelog entry following project standards
parameters:
  - name: description
    type: string
    required: true
    description: Brief description for the changelog entry
---

# /changelog Command

Create a changelog entry documenting work completed.

## Usage

/changelog add-user-authentication
/changelog fix-database-migration
```

### MCP Servers

Define MCP servers in `~/.miau/config/mcp/servers.yaml`. Secrets use `${VAR}` placeholders — actual values go in `.env` (gitignored).

```yaml
servers:
  # npx-based server
  context7:
    command: npx
    args:
      - -y
      - "@upstash/context7-mcp@latest"

  # npx-based server with env vars
  mcp-linear:
    command: npx
    args:
      - -y
      - "@anthropic/mcp-linear"
    env:
      LINEAR_API_KEY: "${LINEAR_API_KEY}"

  # Docker-based server
  github:
    command: docker
    args:
      - run
      - -i
      - --rm
      - -e
      - GITHUB_PERSONAL_ACCESS_TOKEN
      - ghcr.io/github/github-mcp-server
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

  # HTTP server (no local process)
  grep:
    type: http
    url: https://mcp.grep.app
```

Create `~/.miau/config/mcp/.env` with your actual secrets:

```bash
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
```

## Project Setup

When you run `miau project init` inside a repository and select MCP servers, miau creates a `.env.template` in `.ai/mcp/` listing the required variables:

```
.ai/mcp/
  servers.yaml      # MCP server config (committed)
  .env.template     # Required variables (committed)
  .env              # Your actual secrets (gitignored)
```

Copy the template and fill in your values:

```bash
cp .ai/mcp/.env.template .ai/mcp/.env
# Edit .env with your actual tokens/secrets
```

`.env` is excluded from git automatically. Each team member copies the template and provides their own secrets.

## Commands

| Command | Description |
|---------|-------------|
| `miau` | Interactive wizard |
| `miau init` | Initialize global config + link AI tools |
| `miau sync` | Regenerate provider configurations |
| `miau status` | Show configuration status |
| `miau doctor` | Diagnose issues |
| `miau skill list\|add\|remove` | Manage skills |
| `miau agent list\|add\|remove` | Manage agents |
| `miau command list\|add\|remove` | Manage commands |
| `miau mcp list\|add\|remove` | Manage MCP servers |
| `miau provider list\|info` | View provider status |
| `miau project init\|sync\|status` | Manage project-local config |

Use `-f` to force overwrite, `-y` to skip prompts.

## Providers

| Provider | Skills | Agents | MCP |
|----------|--------|--------|-----|
| Claude Code | symlink | AGENTS.md | settings.local.json |
| OpenCode | symlink | converted | opencode.jsonc |
| Gemini CLI | symlink | — | settings.json |
| Copilot | .github/instructions | .github/agents | — |
| Cursor | .cursor/skills/ | .cursor/agents/ | mcp.json |

## License

MIT