Migration Guide

The mewkit migrate command exports your .claude/ kit to 15 external coding-agent tools. This page covers when to use it, what each tool accepts, and how to recover when conflicts surface.

When to migrate

Capability matrix

What each tool can receive from your .claude/ kit:

✓ supported · — not supported by tool

Special cases:

• Antigravity treats agents as a special case of skills. Your Claude Code agents migrate into Antigravity's skills directory.
• Codex commands migrate as Agent Skills (.agents/skills/source-command-<name>/SKILL.md) — Codex custom prompts gave way to skills. Dynamic template syntax ($ARGUMENTS, $1, {...}, !`cmd`, @file) has no skill equivalent; the template migrates verbatim with a manual-adaptation warning.
• Capability resolution adds one generated, bounded instruction block to AGENTS.md and writes .codex/capabilities.json. The block tells the agent to use npx mewkit capabilities resolve --intent "..." --provider codex; the JSON is data-only resolver input, never always-on model context. Re-running migration replaces the managed block without touching user-authored AGENTS.md content.
• Codex rules merge into AGENTS.md as ## Rule: sections (native .rules files only accept prefix_rule() command policies). Orchestration/runtime-only rules are skipped by default; pass --all-rules to merge everything. The merged file is checked against Codex's 32 KiB project_doc_max_bytes budget — over-budget merges warn with the exact config line to add to ~/.codex/config.toml, but mewkit never truncates the file or writes to your home config.
• .mcp.json converts to config.toml [mcp_servers] entries with the opt-in --include-mcp flag (Codex only; project-scoped MCP config loads only in trusted projects). When .mcp.json exists and the flag is off, the preflight tells you the exact re-run command.
• .claude/.env converts to a Codex [shell_environment_policy] scaffold from key names only. Values are never copied; secret-like key names are omitted and counted only as an aggregate warning.
• Hooks only migrate to four tools (Claude Code, Codex, Droid, Gemini CLI). For other tools, mewkit skips hooks with a warning. Codex events are version-gated: recent Codex (0.142+) supports 10 events with hooks enabled by default; older versions fall back to the conservative 6-event table.
• Codex shell hooks (.sh) migrate through generated .cjs wrappers that execute the copied script inside .codex/hooks/. Unsupported shell-family handlers such as .ps1, .bat, .cmd, and .py are reported as skipped with a reason.
• Kilo Code entries are ported from upstream but unverified by mewkit. A runtime warning appears when you select it.

Reference rewriting

Markdown content is rewritten with a fence-aware classifier instead of blanket string replacement:

Every preserved reference appears in the preflight/dry-run report with file:line and a reason — nothing is silently dropped, and no path is ever fabricated. A post-conversion scanner verifies the invariant: any surviving source reference must be explained by a classifier decision, otherwise the run aborts before writing. Codex runs also persist the outcome to .codex/migration-report.json and .codex/migration-report.md, with one row per migrated, skipped, failed, or narrowed artifact.

Quick start

One-shot scaffold + export

# Fresh project, scaffold and export to Cursor in one command
npx mewkit init --migrate-to cursor

# Multiple tools at once
npx mewkit init --migrate-to cursor,codex,droid

# All 15 tools (CI-friendly)
npx mewkit init --migrate-to all

Standalone after init

# Already have a .claude/ — export to one tool
npx mewkit migrate cursor

# Export to all installed tools (auto-detected)
npx mewkit migrate --yes

# Interactive picker
npx mewkit migrate

Idempotent re-runs

mewkit tracks every install in ~/.mewkit/portable-registry.json with SHA-256 checksums for both source and target. Re-running migrate reconciles changes per file using an 8-case decision matrix:

Practical impact: running mewkit upgrade followed by mewkit migrate cursor automatically propagates new agents/skills to Cursor without overwriting your local edits.

Portable evolution manifest

mewkit migrate also reads packages/mewkit/portable-manifest.json from the installed package. This file has one narrow job: clean up old registry-owned paths after MeowKit moves a source item or changes a provider install path.

The portable evolution manifest is not the release checksum manifest and it is not a provider capability manifest. Release manifests verify packaged files. Provider manifests describe supported surfaces. The portable evolution manifest only records real path evolution that must be reconciled once per registry.

Dry runs show manifest cleanup actions without updating ~/.mewkit/portable-registry.json. A successful non-dry-run migration records the applied manifest version so the cleanup does not repeat.

Resolving conflicts

When source AND target both changed since last install, mewkit prompts:

[!] Conflict: cursor/agent/scout
  mewkit updated source since last install
  Target file was also modified (user edits detected)

? How to resolve?
  > Overwrite with mewkit version (lose your edits)
    Keep your version (skip mewkit update)
    Show diff

Options:

Bypass the prompt:

• --force — overwrite all conflicts without asking
• --yes — non-interactive default is "keep your version"

Scope flags

Restrict what gets migrated:

# Only skills
mewkit migrate cursor --only=skills

# Only skills and rules
mewkit migrate cursor --only=skills,rules

# Everything except hooks
mewkit migrate gemini-cli --skip-hooks

# Everything except config and rules
mewkit migrate codex --skip-config --skip-rules

# Merge every rule into AGENTS.md, bypassing the portability filter
mewkit migrate codex --all-rules

# Also convert .mcp.json servers into config.toml [mcp_servers]
mewkit migrate codex --include-mcp

Codex migration report

Codex migrations write two managed report files at the end of every run:

The final summary prints a single verdict line:

Migration: 125 migrated, 67 skipped, 39 need attention -> .codex/migration-report.json

need attention does not necessarily mean the run failed. It means at least one artifact migrated with reduced coverage, preserved an out-of-scope runtime reference, or was intentionally skipped by portability policy.

Project vs. global scope

By default, mewkit writes to project-local paths (./.cursor/rules/, ./.codex/agents/, etc.). Pass --global to write to your home directory (~/.cursor/rules/, ~/.codex/agents/).

# Project scope (default)
mewkit migrate cursor

# Global scope
mewkit migrate cursor --global

# Init + migrate to global
mewkit init --migrate-to cursor --migrate-global

Rule of thumb: project scope keeps the kit confined to one repo. Global scope is for users who want every project on their machine to share the same Cursor/Codex config.

Path collisions

Some tools share install paths. mewkit detects this and emits a banner during the preflight:

[i] Shared target: .agents/skills/ (skills) used by codex + amp + windsurf — each provider writes the same content here

Currently shared paths:

• .agents/skills/ — used by Codex, Cursor, Windsurf, Gemini CLI, Amp (5 tools)
• ~/.agents/skills/ — globally shared between several of the above

When you select multiple sharing providers, mewkit issues distinct install actions per provider, but each writes byte-identical content (same direct-copy format) so the final on-disk state is consistent.

Uninstalling / starting over

The registry tracks every installation. To clean a partial state:

# Remove the registry — next migrate becomes a fresh install
rm ~/.mewkit/portable-registry.json

# Per-tool: delete the tool's directory then re-run
rm -rf .cursor
mewkit migrate cursor

Concurrency

A PID-based file lock at SCOPE/.mewkit/.lock (./.mewkit/.lock for project, ~/.mewkit/.lock for global) prevents two mewkit migrate runs from racing. Stale locks with dead PIDs auto-clear after 60 seconds.

If you see Another mewkit migrate is in progress (PID X), check whether that PID is actually alive:

ps -p <PID>      # Unix
tasklist | grep <PID>   # Windows

If dead, delete the lock manually: rm .mewkit/.lock.

Troubleshooting

"Provider detection failed" in --yes mode

A which probe threw an unexpected error. mewkit refuses to default to "all 15 targets" silently. Pass --all or specify a tool explicitly:

mewkit migrate cursor --yes      # explicit single tool
mewkit migrate --all --yes       # explicit all 15

Codex hooks require recent Codex version

mewkit probes codex --version and picks a version-gated capability table: Codex 0.142+ gets the full 10-event surface (hooks enabled by default), while older or undetectable versions fall back to the conservative 0.124.0-alpha.3 table (6 events, feature flag written). Unsupported events are skipped with a structured warning. Set MEWKIT_CODEX_COMPAT=optimistic to assume the newest capabilities, or MEWKIT_CODEX_COMPAT=strict to force the conservative table.

"Kilo Code support is UNVERIFIED"

This warning is informational only — Kilo Code's registry entry is ported from upstream but no mewkit maintainer has tested it on a live install. If migration fails, please open an issue with the error.

Upgrading mewkit itself

Independent of mewkit migrate, the CLI tool itself updates via:

npx mewkit upgrade           # latest stable
npx mewkit upgrade --beta    # latest beta
npx mewkit upgrade --check   # show available without installing

After upgrading mewkit, your .claude/ kit content does NOT change. Run mewkit init (in a fresh dir) or mewkit upgrade (to refresh the kit) — both flows can chain --migrate-to TOOL to update external tools.

See also

• CLI Commands Reference — every flag with examples
• TDD Optional Migration — older migration guide for the v2.x TDD-optional change