Portability

MeowKit is authored for Claude Code and exported elsewhere. These commands do the exporting and tell you honestly what survives the trip.

migrate

Export your .claude/ kit (agents, commands, skills, config, rules, hooks) to external coding-agent tools.

npx mewkit migrate <tool> [flags]
npx mewkit migrate --all
npx mewkit migrate                    # interactive multiselect

Supported tools: cursor, codex. (claude-code is the source format and is not a valid migration target. Selecting any other provider name errors with this supported list.)

Flags

Model routing

Model routing is per agent, not a central config block. The Codex authored bundle bakes model_reasoning_effort into each .codex/agents/*.toml, derived from the source Claude tier (opus/fable → xhigh, sonnet → high, haiku → medium; inherit agents omit it and inherit Codex's default). model is left unset because Codex model ids are deployment-specific — pin one by editing the agent TOML or via a Codex config profile.

mewkit migrate maps Claude source tiers (opus, sonnet, haiku) but ships no target model IDs in code. When a tier has no Codex model id, the converted agent discloses the source model as a commented hint and inherits the target agent's default.

Capability matrix

What each tool emits at runtime. ✓ migrated · — not migrated.

The matrix reflects what mewkit migrate actually writes per provider. Each provider's contract (providers/{id}/contract.ts) declares which surfaces are first-party documented; surfaces not in that contract are nulled by the runtime disable loop, even if config.ts declares a path for them. See "Known limitations" below for documented-upstream surfaces that the runtime currently skips.

✓ converted from your .claude/ kit · bundle = shipped by the authored Codex bundle · — not supported by tool

Notes:

• Codex does not convert your own agents, commands, or hooks. Toolkit versions of all three ship in the hand-authored Codex bundle; port your custom ones manually. The converter prints a one-line notice when it finds them.
• Codex rules in OpenAI's docs are exec-policy .rules files. MeowKit behavioral rules migrate into AGENTS.md; they are not converted into sandbox exec-policy rules.
• Hooks reach both targets only through their authored bundles — .cjs handlers registered in .codex/hooks.json for Codex and .cursor/hooks.json for Cursor. The legacy .claude→.cursor converter emits no hooks of its own.

Known limitations

The runtime is contract-driven, not config-driven. A provider's config.ts may declare file paths and converter formats for a surface, but unless that surface is listed in the provider's contract.ts surfaces field, the runtime disable loop nulls it before installation. This is intentional — it guarantees that only surfaces with verified first-party documentation are migrated.

Examples

# Preview before any writes
npx mewkit migrate cursor --dry-run

# Single tool, project scope
npx mewkit migrate cursor

# Both tools (uses interactive picker if TTY)
npx mewkit migrate

# Both supported tools, non-interactive (CI-friendly)
npx mewkit migrate --all --yes

# Global install scope
npx mewkit migrate codex --global

# Restrict scope to specific types
npx mewkit migrate cursor --only=skills,rules
npx mewkit migrate codex --skip-hooks

# Force overwrite user edits
npx mewkit migrate cursor --force

Idempotency

mewkit tracks every installation in ~/.mewkit/portable-registry.json with SHA-256 source + target checksums. Re-running migrate reconciles per file:

• Source unchanged + target unchanged → skip
• Source changed + target unchanged → update
• Source unchanged + target edited by user → skip (preserves your edits)
• Source changed + target edited by user → conflict (interactive prompt)
• Source removed + registry entry exists → delete
• Brand new item → install

A mewkit upgrade followed by mewkit migrate cursor propagates kit updates to Cursor without losing local edits.

Exit codes

Concurrent invocations

A PID-based file lock at SCOPE/.mewkit/.lock blocks two mewkit migrate runs from racing on the same registry. Stale locks (dead PID) are auto-cleared after 60 seconds.

providers

Show migration-target provider support (level, role, surfaces). explain-support is an alias that takes a single provider. With --lifecycle, show the capability-adapter view instead: the four support levels, repo-context acquisition tools, storage boundary, and the per-lifecycle-event matrix (which events a provider fires and which it can actually gate/deny on).

npx mewkit providers [<provider>] [--json]
npx mewkit explain-support <provider>
npx mewkit providers --lifecycle              # event × provider matrix (proven-gate markers)
npx mewkit providers <provider> --lifecycle   # one provider: levels, acquisition, lifecycle, evidence

explain-support

An alias of providers, kept because "which providers does this support" and "explain the support matrix" are the same question asked two ways.

npx mewkit explain-support [<provider>] [--json] [--lifecycle]

pack

Manage optional capability packs layered over the base kit.

npx mewkit pack list [--json]
npx mewkit pack add <pack>… [--yes] [--beta]
npx mewkit pack remove <pack>…