sync-agents-settings 0.2.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "sync-agents-settings",
+  "version": "0.4.0",
+  "description": "Sync MCP server configs and instructions from Claude Code to other AI agents (Gemini, Codex, Cursor, Kiro, OpenCode)",
+  "repository": "https://github.com/Leoyang183/sync-agents-settings",
+  "author": {
+    "name": "Leoyang183"
+  },
+  "license": "MIT",
+  "keywords": ["mcp", "sync", "agents", "settings"]
+}

package/README.md

@@ -11,18 +11,42 @@
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?logo=prettier)](https://prettier.io/)
 [![CI](https://github.com/Leoyang183/sync-agents-settings/actions/workflows/ci.yml/badge.svg)](https://github.com/Leoyang183/sync-agents-settings/actions/workflows/ci.yml)
 
-Sync MCP server configurations and instruction files (CLAUDE.md) from **Claude Code** to **Gemini CLI**, **Codex CLI**, **OpenCode**, **Kiro CLI**, and **Cursor**.
+Sync MCP server configurations and instruction files (CLAUDE.md) from **Claude Code** to **Gemini CLI**, **Codex CLI**, **OpenCode**, **Kiro CLI**, **Cursor**, **Kimi CLI**, and **Aider CLI**.
 
 **README translations:** [🇹🇼 繁體中文](docs/i18n/README.zh-tw.md) | [🇨🇳 简体中文](docs/i18n/README.zh-cn.md) | [🇯🇵 日本語](docs/i18n/README.ja.md) | [🇰🇷 한국어](docs/i18n/README.ko.md)
+**Support matrix:** [CLI compatibility matrix](docs/compatibility-matrix.md)
 
 ## Why
 
-If you use Claude Code as your primary AI coding agent but also switch between other agents (Gemini CLI, Codex CLI, OpenCode, Kiro, Cursor) to take advantage of their free tiers or different models, you know the pain — every tool has its own MCP config format, and setting them up one by one is tedious. Same goes for instruction files — CLAUDE.md, GEMINI.md, AGENTS.md all need the same content but in different formats.
+If you use Claude Code as your primary AI coding agent but also switch between other agents (Gemini CLI, Codex CLI, OpenCode, Kiro, Cursor, Kimi CLI) to take advantage of their free tiers or different models, you know the pain — every tool has its own MCP config format, and setting them up one by one is tedious. Same goes for instruction files — CLAUDE.md, GEMINI.md, AGENTS.md all need the same content but in different formats.
 
 This tool lets you configure MCP servers and write instructions once in Claude Code, then sync everywhere with a single command.
 
 ## Quick Start
 
+### Option A: Claude Code Plugin (recommended)
+
+Use directly inside Claude Code with slash commands:
+
+```bash
+# Load the plugin for this session
+claude --plugin-dir /path/to/sync-agents-settings
+
+# Then use slash commands in the conversation:
+#   /sync-list          — list all MCP servers
+#   /sync               — sync MCP configs (with dry-run preview)
+#   /sync-diff           — compare configs between agents
+#   /sync-doctor         — detect config drift and parse errors
+#   /sync-validate       — validate schema and target capabilities
+#   /sync-reconcile      — validate + detect drift + sync only missing
+#   /report-schema       — print or write report JSON schema markdown
+#   /sync-instructions   — sync CLAUDE.md to other agents
+```
+
+The plugin also includes a **sync-awareness skill** that automatically suggests syncing when you edit MCP settings or CLAUDE.md files.
+
+### Option B: CLI via npx
+
 No installation needed — just run with `npx`:
 
 ```bash
@@ -39,7 +63,7 @@ npx sync-agents-settings sync
 npx sync-agents-settings sync-instructions
 ```
 
-## Install (optional)
+### Option C: Global Install
 
 ```bash
 # Global install for the `sync-agents` command
@@ -59,13 +83,60 @@ sync-agents sync --target codex
 sync-agents sync --target opencode
 sync-agents sync --target kiro
 sync-agents sync --target cursor
+sync-agents sync --target kimi
 
 # Sync to Codex project-level config
 sync-agents sync --target codex --codex-home ./my-project/.codex
 
+# Sync to Kimi project-level config
+sync-agents sync --target kimi --kimi-home ./my-project/.kimi
+
 # Compare differences
 sync-agents diff
 
+# Check drift / parse errors between Claude and targets
+sync-agents doctor
+
+# Validate source schema and target capability compatibility
+sync-agents validate
+
+# One-shot safe reconcile (validate + doctor + sync missing)
+sync-agents reconcile --dry-run
+
+# CI-friendly JSON output
+sync-agents reconcile --report json
+
+# CI-friendly JSON output for drift checker
+sync-agents doctor --report json
+
+# CI-friendly JSON output for schema/capability validation
+sync-agents validate --report json
+
+# CI-friendly JSON output for sync result
+sync-agents sync --report json --dry-run
+
+# CI-friendly JSON output for instruction sync
+sync-agents sync-instructions --report json --dry-run --global --target gemini
+
+# CI-friendly JSON output for diff result
+sync-agents diff --report json --target gemini codex
+
+# Note: all --report json outputs include `schemaVersion: 1`
+
+Report schema reference: `docs/report-schema.md`
+
+# Regenerate report schema documentation
+sync-agents report-schema --write docs/report-schema.md
+
+# CI check: ensure report schema doc is up to date
+sync-agents report-schema --check
+
+# Auto-fix from doctor (internally runs reconcile)
+sync-agents doctor --fix --dry-run
+
+# Auto-fix after validation passes
+sync-agents validate --fix --dry-run
+
 # Skip OAuth-only servers (e.g. Slack)
 sync-agents sync --skip-oauth
 
@@ -75,7 +146,23 @@ sync-agents sync --no-backup
 # Verbose output
 sync-agents sync -v
 
-# Sync instruction files (CLAUDE.md → GEMINI.md / AGENTS.md / Kiro steering / Cursor rules)
+# Check only specific targets
+sync-agents doctor --target gemini codex
+
+# Check Codex project-level config drift
+sync-agents doctor --target codex --codex-home ./.codex
+
+# Validate only selected targets and ignore OAuth-only servers
+sync-agents validate --target codex opencode --skip-oauth
+
+# Validation semantics:
+# - blank-only command/url values are treated as missing
+# - OAuth-only servers produce manual-setup warnings without duplicate field errors
+
+# Reconcile selected targets only
+sync-agents reconcile --target gemini codex
+
+# Sync instruction files (CLAUDE.md → GEMINI.md / AGENTS.md / Kiro steering / Cursor rules / Aider conventions)
 sync-agents sync-instructions
 
 # Sync only global instructions
@@ -85,11 +172,17 @@ sync-agents sync-instructions --global
 sync-agents sync-instructions --local
 
 # Sync to specific targets
-sync-agents sync-instructions --target gemini codex
+sync-agents sync-instructions --target gemini codex kimi aider
 
 # Auto-overwrite without prompts (for CI)
 sync-agents sync-instructions --on-conflict overwrite
 
+# Keep legacy behavior: remove standalone @import lines instead of expanding
+sync-agents sync-instructions --import-mode strip
+
+# Allow standalone @import to read files outside current project root (use with care)
+sync-agents sync-instructions --allow-unsafe-imports
+
 # Preview instruction sync
 sync-agents sync-instructions --dry-run
 ```
@@ -115,7 +208,8 @@ pnpm test            # Run tests
                      ├─→ Reader ─→ UnifiedMcpServer[] ─┼─→ OpenCode Writer ─→ ~/.config/opencode/opencode.json
 ~/.claude/plugins/ ──┘                            │
                                                  ├─→ Kiro Writer     ─→ ~/.kiro/settings/mcp.json
-                                                 └─→ Cursor Writer   ─→ ~/.cursor/mcp.json
+                                                 ├─→ Cursor Writer   ─→ ~/.cursor/mcp.json
+                                                 └─→ Kimi Writer     ─→ ~/.kimi/mcp.json
 ```
 
 | Stage | Description |
@@ -126,6 +220,7 @@ pnpm test            # Run tests
 | **OpenCode Writer** | JSON → JSON, `command`+`args` → merged `command` array, `env` → `environment`, `type: "local"`/`"remote"` |
 | **Kiro Writer** | Same format as Claude, `${VAR:-default}` → expanded |
 | **Cursor Writer** | Same format as Claude, `${VAR:-default}` → expanded |
+| **Kimi Writer** | Same format as Claude, `${VAR:-default}` → expanded |
 
 ### Instruction Sync (`sync-instructions`)
 
@@ -134,24 +229,37 @@ Syncs CLAUDE.md instruction files to each target's native format:
 ```
                                           ┌─→ ~/.gemini/GEMINI.md             (plain copy)
                                           ├─→ ~/.codex/AGENTS.md              (plain copy)
-~/.claude/CLAUDE.md ─→ filter @imports ──┼─→ ~/.config/opencode/AGENTS.md    (plain copy)
+~/.claude/CLAUDE.md (+ ~/.claude/rules/*.md) ─→ expand @imports ──┼─→ ~/.config/opencode/AGENTS.md    (plain copy)
+                                          ├─→ ~/.kimi/AGENTS.md               (plain copy)
                                           ├─→ ~/.kiro/steering/claude-instructions.md  (+ inclusion: always)
                                           └─→ ⚠ Cursor global not supported  (SQLite)
 
                                           ┌─→ ./GEMINI.md                     (plain copy)
-                                          ├─→ ./AGENTS.md                     (Codex + OpenCode share)
-./CLAUDE.md ──────────→ filter @imports ──┼─→ .kiro/steering/claude-instructions.md    (+ inclusion: always)
+                                          ├─→ ./AGENTS.md                     (Codex + OpenCode + Kimi share)
+./.claude/CLAUDE.md (fallback: ./CLAUDE.md) + ./.claude/rules/*.md ─→ expand @imports ──┼─→ .kiro/steering/claude-instructions.md    (+ inclusion: always)
                                           └─→ .cursor/rules/claude-instructions.mdc   (+ alwaysApply: true)
 ```
 
 | Target | Global | Local | Format Transform |
 |--------|--------|-------|------------------|
-| Gemini | `~/.gemini/GEMINI.md` | `./GEMINI.md` | Plain copy (filter `@import` lines) |
-| Codex | `~/.codex/AGENTS.md` | `./AGENTS.md` | Plain copy (filter `@import` lines) |
-| OpenCode | `~/.config/opencode/AGENTS.md` | `./AGENTS.md` (shared with Codex) | Plain copy (filter `@import` lines) |
+| Gemini | `~/.gemini/GEMINI.md` | `./GEMINI.md` | Plain copy (expand standalone `@import` lines) |
+| Codex | `~/.codex/AGENTS.md` | `./AGENTS.md` | Plain copy (expand standalone `@import` lines) |
+| OpenCode | `~/.config/opencode/AGENTS.md` | `./AGENTS.md` (shared with Codex) | Plain copy (expand standalone `@import` lines) |
+| Kimi | `~/.kimi/AGENTS.md` | `./AGENTS.md` (shared with Codex/OpenCode) | Plain copy (expand standalone `@import` lines) |
+| Aider | `~/.aider/CONVENTIONS.md` | `.aider/CONVENTIONS.md` | Plain copy + upsert `read` entry in `.aider.conf.yml` |
 | Kiro | `~/.kiro/steering/claude-instructions.md` | `.kiro/steering/claude-instructions.md` | Add `inclusion: always` frontmatter |
 | Cursor | Not supported (SQLite) | `.cursor/rules/claude-instructions.mdc` | Add `alwaysApply: true` frontmatter |
 
+Notes:
+- Local source resolution prefers `./.claude/CLAUDE.md`, then falls back to `./CLAUDE.md`.
+- Extra rules in `.claude/rules/**/*.md` are appended automatically (unless already included via `@import`).
+- If a rule file has frontmatter `paths`, it is included only when at least one project file matches.
+- `@import` handling defaults to `inline` (expand). Use `--import-mode strip` to remove standalone import lines.
+- By default, standalone `@import` can only read files inside the current project root. Use `--allow-unsafe-imports` to opt out.
+- Inline import expansion has guardrails (`max depth: 20`, `max files: 200`) to avoid runaway recursion.
+- Aider sync also upserts `.aider.conf.yml` `read` so `CONVENTIONS.md` is loaded automatically (global/project follows the sync scope).
+- Kimi CLI currently loads `AGENTS.md` from the working directory. `~/.kimi/AGENTS.md` is synced as a reusable global template.
+
 When a target file already exists, you'll be prompted to choose: **overwrite**, **append** (keep existing + add CLAUDE.md below), or **skip**. Use `--on-conflict overwrite|append|skip` for non-interactive mode.
 
 **Safety mechanisms:**
@@ -277,15 +385,21 @@ Writes to **`~/.cursor/mcp.json`** → `mcpServers` object.
 
 Same format as Claude Code. `${VAR:-default}` syntax in URLs is auto-expanded during sync.
 
+### Target: Kimi CLI
+
+Writes to **`~/.kimi/mcp.json`** by default. Use `--kimi-home <path>` to sync to a custom base directory (for example, project-level `.kimi/`).
+
+Same format as Claude Code. `${VAR:-default}` syntax in URLs is auto-expanded during sync.
+
 ## Transport Type Mapping
 
-| Claude Code | Gemini CLI | Codex CLI | OpenCode | Kiro CLI | Cursor |
-|------------|-----------|----------|----------|----------|--------|
-| `command` + `args` (stdio) | `command` + `args` | `command` + `args` | `type: "local"`, `command: [cmd, ...args]` | same as Claude | same as Claude |
-| `type: "http"` + `url` | `httpUrl` | `url` | `type: "remote"`, `url` | same as Claude | same as Claude |
-| `type: "sse"` + `url` | `url` | `url` | `type: "remote"`, `url` | same as Claude | same as Claude |
-| `env` | `env` | `env` | `environment` | `env` | `env` |
-| `oauth` | skipped | skipped | skipped | skipped | skipped |
+| Claude Code | Gemini CLI | Codex CLI | OpenCode | Kiro CLI | Cursor | Kimi CLI |
+|------------|-----------|----------|----------|----------|--------|----------|
+| `command` + `args` (stdio) | `command` + `args` | `command` + `args` | `type: "local"`, `command: [cmd, ...args]` | same as Claude | same as Claude | same as Claude |
+| `type: "http"` + `url` | `httpUrl` | `url` | `type: "remote"`, `url` | same as Claude | same as Claude | same as Claude |
+| `type: "sse"` + `url` | `url` | `url` | `type: "remote"`, `url` | same as Claude | same as Claude | same as Claude |
+| `env` | `env` | `env` | `environment` | `env` | `env` | `env` |
+| `oauth` | skipped | skipped | skipped | skipped | skipped | skipped |
 
 ## Backup
 
@@ -306,8 +420,10 @@ Every sync automatically backs up all affected config files to `~/.sync-agents-b
 ├── .kiro/
 │   └── settings/
 │       └── mcp.json              # ← ~/.kiro/settings/mcp.json
-└── .cursor/
-    └── mcp.json                  # ← ~/.cursor/mcp.json
+├── .cursor/
+│   └── mcp.json                  # ← ~/.cursor/mcp.json
+└── .kimi/
+    └── mcp.json                  # ← ~/.kimi/mcp.json
 ```
 
 Use `--no-backup` to skip. Target directories that don't exist (CLI not installed) will be skipped with a warning, not created.
@@ -330,18 +446,48 @@ Use `--no-backup` to skip. Target directories that don't exist (CLI not installe
 | Kiro CLI (project) | `.kiro/settings/mcp.json` in project root | JSON |
 | Cursor (global) | `~/.cursor/mcp.json` | JSON |
 | Cursor (project) | `.cursor/mcp.json` in project root | JSON |
+| Kimi CLI (global) | `~/.kimi/mcp.json` | JSON |
+| Kimi CLI (project) | `.kimi/mcp.json` (use `--kimi-home ./.kimi`) | JSON |
 
 ### Instruction Files
 
 | Tool | Global Path | Project Path | Format |
 |------|------------|-------------|--------|
-| Claude Code | `~/.claude/CLAUDE.md` | `./CLAUDE.md` | Markdown |
+| Claude Code | `~/.claude/CLAUDE.md` | `./.claude/CLAUDE.md` (fallback `./CLAUDE.md`) | Markdown |
 | Gemini CLI | `~/.gemini/GEMINI.md` | `./GEMINI.md` | Markdown |
 | Codex CLI | `~/.codex/AGENTS.md` | `./AGENTS.md` | Markdown |
 | OpenCode | `~/.config/opencode/AGENTS.md` | `./AGENTS.md` | Markdown |
+| Kimi CLI | `~/.kimi/AGENTS.md` | `./AGENTS.md` | Markdown |
 | Kiro CLI | `~/.kiro/steering/claude-instructions.md` | `.kiro/steering/claude-instructions.md` | Markdown + frontmatter |
 | Cursor | Not supported (SQLite) | `.cursor/rules/claude-instructions.mdc` | MDC (Markdown + frontmatter) |
 
+## Claude Code Plugin
+
+This project can be used as a Claude Code plugin, providing slash commands and a contextual skill directly inside Claude Code conversations.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/sync` | Sync MCP server configs to other agents (with dry-run preview and confirmation) |
+| `/sync-list` | List all MCP servers configured in Claude Code |
+| `/sync-diff` | Compare MCP configs between Claude and other agents |
+| `/sync-instructions` | Sync CLAUDE.md instruction files to other agent formats |
+
+### Sync-Awareness Skill
+
+The plugin includes a skill that automatically detects when you're editing MCP settings (`.claude.json`, `.mcp.json`) or `CLAUDE.md` files, and suggests syncing to other agents.
+
+### Plugin Development
+
+```bash
+# Validate plugin structure
+claude plugins validate /path/to/sync-agents-settings
+
+# Test locally (loads plugin for this session only)
+claude --plugin-dir /path/to/sync-agents-settings
+```
+
 ## Limitations
 
 - **OAuth servers** (e.g. Slack with `oauth.clientId`) are synced as URL-only — you'll need to authenticate manually in each CLI
@@ -358,4 +504,3 @@ Use `--no-backup` to skip. Target directories that don't exist (CLI not installe
 ## License
 
 MIT
-

package/commands/report-schema.md

@@ -0,0 +1,25 @@
+---
+name: report-schema
+description: Print or write markdown documentation for JSON report schema
+---
+
+Generate report schema markdown from code metadata (`COMMAND_REQUIRED_FIELDS`) and print to stdout or write to file.
+
+## Usage
+
+```bash
+# Print to stdout
+npx sync-agents-settings report-schema
+
+# Write to docs file
+npx sync-agents-settings report-schema --write docs/report-schema.md
+
+# CI check: fail if docs/report-schema.md is stale or missing
+npx sync-agents-settings report-schema --check
+```
+
+## Notes
+
+- Use this command after changing report payload fields or parser validation rules.
+- The generated file should include the "Required Fields (Generated)" section.
+- `--check` exits with code `1` when target schema file is missing or outdated.

package/commands/sync-diff.md

@@ -0,0 +1,32 @@
+---
+name: sync-diff
+description: Compare MCP server configurations between Claude Code and other AI agents
+---
+
+Compare which MCP servers exist in Claude Code vs other AI agents.
+
+## Arguments
+
+The user may pass target names: `/sync-diff gemini`
+If no targets specified, compare all targets (gemini, codex, opencode, kiro, cursor, kimi).
+
+Optional flags:
+- `--report json` — output machine-readable JSON summary (CI-friendly)
+
+## Execution Flow
+
+1. Parse targets from user arguments. Run:
+   `npx sync-agents-settings diff --target <targets>`
+
+2. Present the comparison for each target:
+   - **Shared** — servers that exist in both Claude and the target
+   - **Only in Claude** — servers that could be synced to the target
+   - **Only in target** — servers that exist in the target but not in Claude
+
+3. If there are servers "Only in Claude", suggest: "Run `/sync` to sync these servers to the target agents."
+   - If `--report json` is used, return raw JSON output and avoid text post-processing.
+
+## Error Handling
+
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.
+- Note: Codex diff shows a message to use `codex mcp list` instead (CLI limitation).

package/commands/sync-doctor.md

@@ -0,0 +1,43 @@
+---
+name: sync-doctor
+description: Detect MCP config drift and parse errors between Claude Code and target AI agents
+---
+
+Check whether target MCP configs are in sync with Claude Code, without writing any files.
+
+## Arguments
+
+The user may pass target names: `/sync-doctor gemini codex`
+If no targets specified, check all targets (gemini, codex, opencode, kiro, cursor, kimi).
+
+Optional flags:
+- `--skip-oauth` — ignore OAuth-only servers from Claude source
+- `--codex-home <path>` — check project-level Codex config (e.g. `./.codex`)
+- `--kimi-home <path>` — check project-level Kimi config (e.g. `./.kimi`)
+- `--fix` — if drift exists, auto-run reconcile to add missing servers
+- `--dry-run` — with `--fix`, preview only
+- `--no-backup` — with `--fix`, skip backup before writing
+- `--report json` — emit machine-readable JSON report
+
+## Execution Flow
+
+1. Parse targets and flags from user arguments.
+2. Run:
+   `npx sync-agents-settings doctor --target <targets>`
+   Add `--skip-oauth` / `--codex-home` / `--kimi-home` when specified.
+3. Present results per target:
+   - `No drift` when fully in sync
+   - `Missing in <target>` when Claude has servers not present in target
+   - `Extra in <target>` when target has servers absent in Claude
+   - `Unavailable` if target directory is missing
+   - `Parse error` when target config is malformed
+4. If drift exists, suggest running `/sync` to reconcile.
+   - Or run `/sync-doctor --fix` to reconcile automatically.
+
+## Error Handling
+
+- Exit code `1` means drift detected.
+- Exit code `2` means config parse error detected.
+- With `--fix`, failure reasons are specific: parse-related (`target config parse error`) or validation-related (`validation errors detected`) before exiting `2`.
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.
+- `--report json` cannot be used with `--fix` on doctor (use `reconcile --report json` instead).

package/commands/sync-instructions.md

@@ -0,0 +1,50 @@
+---
+name: sync-instructions
+description: Sync CLAUDE.md instruction files to other AI agents (Gemini, Codex, OpenCode, Kiro, Cursor, Kimi)
+---
+
+Sync CLAUDE.md instruction files from Claude Code format to other AI agent formats.
+
+## Arguments
+
+The user may pass target names: `/sync-instructions gemini codex`
+If no targets specified, sync to all targets.
+
+The user may also pass flags:
+- `--no-backup` — skip creating backup of target instruction files
+- `--import-mode inline|strip` — how to handle standalone `@import` lines (`inline` = expand, `strip` = remove line)
+- `--report json` — output machine-readable JSON summary (CI-friendly)
+
+## Execution Flow
+
+1. Ask the user which scope to sync:
+   - **Global** (`~/.claude/CLAUDE.md`) — syncs to agent-specific global instruction files
+   - **Local** (`./.claude/CLAUDE.md` in current directory, fallback `./CLAUDE.md`) — syncs to project-level instruction files
+   - **Both** (default) — syncs both global and local
+
+2. Parse targets from user arguments. Build the dry-run command:
+   `npx sync-agents-settings sync-instructions --dry-run [--global|--local] --target <targets>`
+   Omit `--global`/`--local` if syncing both (this is the CLI default).
+   Add `--no-backup` if the user specified it.
+
+3. Run the dry-run command. Present what will be written:
+   - Which instruction files will be created or updated
+   - Which targets will be skipped (e.g., Cursor global is unsupported — uses SQLite)
+
+4. If any target files already exist, ask the user what to do:
+   - **Overwrite** — replace the existing file entirely
+   - **Append** — add Claude instructions after the existing content
+   - **Skip** — leave the existing file untouched
+
+5. Run the actual command. IMPORTANT: Always pass `--on-conflict <action>` to prevent the CLI from entering interactive mode (which does not work in Claude Code's bash execution):
+   `npx sync-agents-settings sync-instructions [--global|--local] --target <targets> --on-conflict <action>`
+   Add `--no-backup` if the user specified it.
+
+6. Present the final results: which files were synced, appended, or skipped.
+   - If `--report json` is used, return raw JSON output and avoid text post-processing.
+
+## Error Handling
+
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.
+- If CLAUDE.md source file doesn't exist: the CLI will report it. Inform the user which file is missing.
+- With `--report json` and non-dry-run mode, pass both `--on-conflict` and `--no-backup` to avoid interactive prompts and non-JSON logs.

package/commands/sync-list.md

@@ -0,0 +1,19 @@
+---
+name: sync-list
+description: List all MCP servers configured in Claude Code with transport type and source
+---
+
+List all MCP servers that Claude Code knows about.
+
+## Execution Flow
+
+1. Run: `npx sync-agents-settings list`
+
+2. Present the output to the user in a readable format:
+   - Group servers by transport type (STDIO, HTTP, SSE)
+   - Show the source of each server (config = from ~/.claude.json, plugin = from Claude plugin)
+   - Highlight any servers that require OAuth authentication
+
+## Error Handling
+
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.

package/commands/sync-reconcile.md

@@ -0,0 +1,41 @@
+---
+name: sync-reconcile
+description: Validate + detect drift + sync only missing MCP servers in one safe flow
+---
+
+Run a safe one-shot reconcile pipeline:
+1) validate schema/capability
+2) detect drift
+3) sync only missing servers
+
+## Arguments
+
+The user may pass target names: `/sync-reconcile gemini codex`
+If no targets are specified, reconcile all targets.
+
+Optional flags:
+- `--dry-run` — preview only, no writes
+- `--no-backup` — skip backup before write
+- `--skip-oauth` — ignore OAuth-only servers
+- `--codex-home <path>` — custom Codex config directory
+- `--kimi-home <path>` — custom Kimi config directory
+- `--report json` — emit machine-readable JSON only (for CI)
+
+## Execution Flow
+
+1. Build command:
+   `npx sync-agents-settings reconcile --target <targets>`
+   Include user-provided flags.
+2. Run with `--dry-run` first if user didn't explicitly request real write.
+3. Present output:
+   - validation errors/warnings
+   - drift summary
+   - servers added/skipped per target
+4. If dry-run was used and output is acceptable, ask user whether to run without `--dry-run`.
+5. In automation/CI, prefer `--report json` and parse the output programmatically.
+
+## Error Handling
+
+- Exit code `2`: validation error or target parse error (must fix before sync).
+- Exit code `0`: reconcile finished (or no drift).
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.

package/commands/sync-validate.md

@@ -0,0 +1,42 @@
+---
+name: sync-validate
+description: Validate Claude MCP schema and target capability compatibility before syncing
+---
+
+Validate MCP server definitions from Claude Code against target agent capabilities.
+
+## Arguments
+
+The user may pass target names: `/sync-validate codex opencode`
+If no targets are specified, validate all targets (gemini, codex, opencode, kiro, cursor, kimi).
+
+Optional flags:
+- `--skip-oauth` — ignore OAuth-only servers from validation
+- `--fix` — after validation passes, auto-run reconcile
+- `--dry-run` — with `--fix`, preview only
+- `--no-backup` — with `--fix`, skip backup before writing
+- `--report json` — emit machine-readable JSON report
+
+## Execution Flow
+
+1. Parse targets and flags from user arguments.
+2. Run:
+   `npx sync-agents-settings validate --target <targets>`
+   Add `--skip-oauth` if requested.
+3. Present issues grouped by target:
+   - `error` issues: invalid schema that cannot be converted safely
+   - `warning` issues: lossy conversion risk or manual setup needed
+   - `command` / `url` with blank-only values are treated as missing and reported as `error`
+   - OAuth-only servers emit `OAUTH_MANUAL_SETUP_REQUIRED` warning only (no duplicate transport-field errors)
+4. If errors exist, tell the user to fix them before running `/sync`.
+5. If only warnings exist, allow user to proceed based on risk tolerance.
+6. If `--fix` is provided and no validation errors exist, run reconcile automatically.
+   - If no drift is found, return a noop result ("Nothing to fix") instead of reporting reconcile success.
+
+## Error Handling
+
+- Exit code `2` means validation errors were found.
+- Exit code `0` means no errors (warnings may still exist).
+- With `--fix`, failure reasons are specific: parse-related (`target config parse error`) or validation-related (`validation errors detected`) before exiting `2`.
+- If `npx` fails: suggest `npm install -g sync-agents-settings` as fallback.
+- `--report json` cannot be used with `--fix` on validate (use `reconcile --report json` instead).

package/commands/sync.md

@@ -0,0 +1,44 @@
+---
+name: sync
+description: Sync MCP server configurations from Claude Code to other AI agents (Gemini, Codex, OpenCode, Kiro, Cursor, Kimi)
+---
+
+Sync MCP server settings from Claude Code to other AI coding agents.
+
+## Arguments
+
+The user may pass target names after the command: `/sync gemini codex`
+If no targets specified, sync to all targets (gemini, codex, opencode, kiro, cursor, kimi).
+
+The user may also pass flags:
+- `--skip-oauth` — skip MCP servers that require OAuth authentication
+- `--no-backup` — skip creating backup of target config files
+- `--codex-home <path>` — custom Codex config directory
+- `--kimi-home <path>` — custom Kimi config directory
+- `--report json` — output machine-readable JSON summary (CI-friendly)
+
+## Execution Flow
+
+1. Parse targets from user arguments. Build the command:
+   `npx sync-agents-settings sync --dry-run --target <targets>`
+   Add `--skip-oauth` or `--no-backup` if the user specified them.
+
+2. Run the dry-run command using bash. This previews what will change without writing files.
+
+3. Present the results to the user:
+   - Servers that will be **added** to each target
+   - Servers that will be **skipped** (already exist or unsupported)
+   - If all servers are skipped, inform the user and stop here.
+
+4. Ask the user: "Proceed with sync?"
+
+5. If confirmed, run the same command without `--dry-run`:
+   `npx sync-agents-settings sync --target <targets>`
+
+6. Present the final results.
+   - If `--report json` is used, return raw JSON and avoid text post-processing.
+
+## Error Handling
+
+- If `npx` fails with "command not found" or network error: suggest `npm install -g sync-agents-settings` as fallback.
+- If the CLI exits with non-zero code: show the stderr output and suggest checking that target agent directories exist.

package/dist/backup.d.ts

@@ -1,2 +1,2 @@
 export declare function createBackup(filePaths: string[]): string;
-export declare function getFilesToBackup(targets: string[], codexConfigPath?: string): string[];
+export declare function getFilesToBackup(targets: string[], codexConfigPath?: string, kimiConfigPath?: string): string[];

package/dist/backup.js

@@ -23,7 +23,7 @@ export function createBackup(filePaths) {
     }
     return backupDir;
 }
-export function getFilesToBackup(targets, codexConfigPath) {
+export function getFilesToBackup(targets, codexConfigPath, kimiConfigPath) {
     const files = [PATHS.claudeJson, PATHS.claudeSettings];
     if (targets.includes("gemini")) {
         files.push(PATHS.geminiSettings);
@@ -37,6 +37,9 @@ export function getFilesToBackup(targets, codexConfigPath) {
     if (targets.includes("kiro")) {
         files.push(PATHS.kiroMcpConfig);
     }
+    if (targets.includes("kimi")) {
+        files.push(kimiConfigPath ?? PATHS.kimiMcpConfig);
+    }
     if (targets.includes("cursor")) {
         files.push(PATHS.cursorMcpConfig);
     }