Runtime Commands

Runtime tools for managing your MeowKit project. Run from your project root.

doctor

Diagnose environment issues with auto-fix for permissions.

npx mewkit doctor [--report]

Checks: Node.js 20+, Python 3.9+, Git, .claude/ structure, hooks executable, scripts present, memory writable, MCP config, Python venv, config validity.

Auto-fixes: Hook file permissions (chmod +x).

setup

Guided post-scaffold configuration. Each step is idempotent.

npx mewkit setup [--only=<step>]

npx mewkit setup              # Run all steps
npx mewkit setup --only=venv  # Run single step

task

Create and manage structured task files. See Task Commands for details.

npx mewkit task new --type feature "Add user auth"
npx mewkit task list [--all] [--status done]

validate

Verify .claude/ structure integrity.

npx mewkit validate

Checks: Agents (10+), skills (30+), commands dir, modes (5+), rules (10+), hooks executable, scripts present, settings.json, CLAUDE.md, config file. In the MeowKit authoring checkout, the full sweep also reports provider-specific vocabulary found in generic skill bodies as advisory portability WARNs; --strict promotes WARNs to errors. Run a focused suite with any of the flags below (no flag = the full sweep).

budget

View token usage and cost tracking.

npx mewkit budget [--monthly] [--session [id]] [--day [YYYY-MM-DD]]

Behavior:

• Without filters, budget shows the latest 10 rows and the all-time token total.
• --session resolves the current session from HOOK_SESSION_ID first, then session-state/last-session-id.
• --day without a value uses today.
• Filters compose, so --session --day reports the intersection.

Examples:

npx mewkit budget
npx mewkit budget --monthly
npx mewkit budget --session
npx mewkit budget --session 9adf6a6b-9fbf-45ca-b36b-b0dd55356ac1
npx mewkit budget --day
npx mewkit budget --day 2026-05-01
npx mewkit budget --session --day 2026-05-01

budget context

Estimate the loadable .claude/ context size for a profile (the context-budget guardrail; also wired into CI).

npx mewkit budget context --profile <core|developer|full> [--fail-over N] [--json]

--fail-over N exits non-zero when the estimated loadable context exceeds N tokens.

memory

View or manage cross-session memory.

npx mewkit memory              # Summary (line counts, pattern count)
npx mewkit memory --show       # Display summary of curated memory stores
npx mewkit memory --stats      # Sessions captured, patterns learned
npx mewkit memory --clear      # Clear all memory (with confirmation)

wiki

Long-term, gated, provenance-bearing project knowledge with full-text search. Agents may only propose candidates; a human approve (which always re-scans) is the only path to a canonical page. Canonical files live under tasks/wikis/<slug>/; .claude/memory/wiki-index.db is a derived, rebuildable FTS index. Wiki content is DATA, never an instruction.

npx mewkit wiki init <slug> --title "<title>"
npx mewkit wiki propose <slug> --title T --file F [--origin agent] [--source-id ID]… [--reuse-scope S] [--salience-json f.json]
npx mewkit wiki approve <slug> <candidate-id> --by <name>
npx mewkit wiki reject <slug> <candidate-id> --reason "<r>"
npx mewkit wiki search "<query>" [--json]
npx mewkit wiki hint "<query>"
npx mewkit wiki context "<keywords>" [--max-pages N] [--json] [--include-content]
npx mewkit wiki handoff suggest --skill <name> --from <artifact> --slug <s> [--json]
npx mewkit wiki handoff propose --skill <name> --from <artifact> --slug <s>
npx mewkit wiki handoff profiles [--json]
npx mewkit wiki list <slug>
npx mewkit wiki render <slug> [--out file.html]
npx mewkit wiki reindex

index

Build or refresh the derived SQLite index (.claude/memory/wiki-index.db) from the canonical append logs (.claude/memory/*.jsonl) and the wiki tree. Disposable and deterministic — delete it and re-run to get an identical index.

npx mewkit index [--json]

query

Run read-only aggregate queries over the derived index (events by type, runs, friction by responsibility, cost by model). Requires a prior mewkit index.

npx mewkit query [--json]

inventory

Report harness-artifact coverage. With --substrate, map artifacts onto the responsibility taxonomy (covered / partial / missing); --emit rewrites the generated harness-substrate.md view.

npx mewkit inventory [--json]
npx mewkit inventory --substrate [--emit]
npx mewkit inventory --stale | --critical | --portable-missing | --check | --emit-counts

trace

Inspect the append-only trace log for entropy and recurring friction, and record friction inline so future sessions can recall it. Advisory — always exits 0.

npx mewkit trace audit            # orphaned / stale / unverified / repeated-friction signals
npx mewkit trace propose          # group repeated friction (≥2) into advisory backlog items
npx mewkit trace score            # entropy score
npx mewkit trace --friction "<note>" [--responsibility <r>] [--commit]

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>…

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

capabilities

Inspect and resolve the capability manifest — the semantic map of installed skills/agents/commands/hooks plus authored tool and context/state services. The manifest is a resolution surface; it is never injected into a model session. The CLI reads the live .claude/ install when present; a Codex-migrated project without it falls back to the validated .codex/capabilities.json projection written by mewkit migrate codex.

npx mewkit capabilities list [--json]
npx mewkit capabilities explain <id> [--json]
npx mewkit capabilities resolve --intent "implement this feature" [--provider <id>] [--json]
npx mewkit capabilities view          # render the trigger-registry table from the manifest
npx mewkit capabilities bootstrap [--provider <id>]   # the always-visible discovery bootstrap
npx mewkit capabilities projections [--json]          # per-provider discovery + 4 support levels

context

Task-scoped repository-context evidence — an on-demand freshness + provenance ledger, not a retrieval engine. MeowKit records and verifies evidence; the host's own tools acquire the content. Each path resolves to its own owning repository, so a folder containing many repos (e.g. an Aspire-style parent) never conflates their context.

npx mewkit context resolve <path> [--root <boundary>] [--json]         # owning repo, revision, content hash, redaction
npx mewkit context check <envelope.json> [--root <boundary>] [--json]  # per-path freshness, grouped by owning repo
npx mewkit context record --task <id> <envelope.json> [--root <boundary>] [--json]  # merge evidence into a durable task record

build-plugin

Regenerate the native plugin distribution (plugin/ payload + Claude/Codex marketplaces) from .claude/. Release tooling — run after editing .claude/ outside a release, then npx mewkit validate --plugin.

npx mewkit build-plugin [--json]

verdict-gate

Gate 2 proof-bundle check. Reads a machine-readable review verdict and exits 0 (PASS / PASS_WITH_RISK or a tolerated legacy markdown-only verdict), 1 (BLOCKED / invalid / missing), or 2 (usage error).

npx mewkit verdict-gate <slug | path-to-verdict.json>

upgrade

Update mewkit to the latest version.

npx mewkit upgrade [--check] [--beta] [--list]

Examples:

npx mewkit upgrade              # Upgrade to latest stable
npx mewkit upgrade --beta       # Upgrade to latest beta
npx mewkit upgrade --check      # Check without installing
npx mewkit upgrade --list       # Show all versions

Output of --list:

Channels:
  stable:  1.2.0
  beta:    1.3.0-beta.2

Recent versions:
  1.2.0 (installed)
  1.1.1
  1.1.0
  1.0.0

status

Print version, channel, and current config.

npx mewkit status

Shows: MeowKit version with channel indicator (stable/beta), project config from .claude/meowkit.config.json.

visual-plan

Structured visual review for UI-bearing plans. The canonical artifact visual-plan/plan.json (schema visual-plan/v1) is a coverage ledger + canvas (lanes, surface-locked artboards, semantic-HTML wireframes, connectors, annotations). Deterministic subcommands validate and gate it; edit/view serve a transient 127.0.0.1 React studio that renders and edits it.

npx mewkit visual-plan <subcommand> <plan-dir> [flags]

Subcommands

Flags

Security

• The studio server binds 127.0.0.1 only; Host-header guarded against DNS rebinding.
• Strict CSP (script-src 'self'); path traversal blocked on the static server.
• Wireframe HTML is DOMPurify-sanitized at BOTH save and render time via one shared allowlist.
• Writes use optimistic concurrency: PATCH requires If-Match; a stale ETag returns 409.
• Feedback batch ids are charset-validated before any path join; batches + receipts are write-once.

Notes

• If the studio bundle is missing at dist/visual-plan-web/, run npm run build:web in the mewkit package to produce it.
• The deterministic contract commands (validate/status/approve/rehash/prepare-feedback/apply-feedback/patch) run with no browser and no network.

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, droid, opencode, goose, gemini-cli, antigravity, github-copilot, amp, kilo, kiro, roo, windsurf, cline, openhands. (claude-code is the source format and is not a valid migration target.)

Flags

Model routing

mewkit migrate reads model routing from project config before converting agents and commands:

1. .meowkit.config.json
2. .claude/meowkit.config.json (legacy fallback)
3. Target-agent defaults when no config is present

The migration maps Claude source tiers (opus, sonnet, haiku) to configured target tiers (heavy, balanced, light). It does not ship target model IDs in code. If a provider/tier is missing, the migrated item inherits the target agent's default model.

{
  "modelRouting": {
    "providers": {
      "codex": {
        "tiers": {
          "heavy": { "model": "your-codex-heavy-model", "reasoningEffort": "xhigh" },
          "balanced": { "model": "your-codex-balanced-model", "reasoningEffort": "high" },
          "light": { "model": "your-codex-light-model", "reasoningEffort": "medium" }
        }
      },
      "opencode": {
        "default": { "model": "your-provider/your-model" }
      }
    }
  }
}

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.

Notes:

• Codex command migration is disabled until OpenAI documents a custom command directory. Codex's documented slash/app commands remain built in to Codex itself.
• 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: only Codex migrates hooks. Other providers' hook surfaces are documented upstream but currently disabled — see "Known limitations".
• Shell hooks (.sh/.ps1/.bat) are filtered at discovery — only node-runnable hooks (.cjs/.mjs/.js) migrate.
• Kilo Code is [unverified] — config paths are ported verbatim from upstream but no real install was tested; the contract is empty and migration emits nothing.
• Roo Code is [deprecated] — upstream announced product shutdown effective May 15, 2026; the contract is empty and migration emits nothing even with --force.

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. The trade-off: some surfaces are documented upstream but not yet enabled in the contract.

Providers whose contracts are intentionally empty (migration emits nothing):

• Kilo Code — config declares modes/skills/rules/instructions paths, but the contract is empty. The adapter is kept for compatibility; converter output has not been verified against a real Kilo install. Migration emits nothing until the contract is populated.
• Roo Code — upstream shut down on May 15, 2026. The contract is empty by design even though --force allows selecting Roo as a target.
• OpenHands — config declares paths, but no first-party portable-surface contract has been verified. Migration emits nothing.

Documented upstream but not yet enabled in the contract:

• Gemini CLI hooks — Gemini documents hooks via .gemini/settings.json (https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md), and a converter (gemini-hook-event-map.ts) exists, but the contract currently disables this surface. Hook migration is limited to Codex.
• Droid rules and hooks — Factory documents .factory/rules/ (https://docs.factory.ai/guides/power-user/rules-conventions) and a settings-based hooks system (https://docs.factory.ai/cli/configuration/hooks-reference); both surfaces are disabled by contract today.
• Kiro IDE hooks — Kiro documents hooks (https://kiro.dev/docs/hooks/); neither config.ts nor contract.ts currently expose a Kiro hooks path or converter.
• Cline hooks and slash-command workflows — Cline documents hooks (https://docs.cline.bot/features/hooks/hook-reference) and slash-command workflows (https://docs.cline.bot/features/slash-commands/workflows/index); neither surface has a converter in config.ts and both are disabled by contract.
• OpenCode config (AGENTS.md) — OpenCode documents config via AGENTS.md (https://opencode.ai/docs/config); config.ts declares the path, but the contract currently exposes only agents and commands.

Filing an issue or PR with a verified converter output is the path to enabling any of the above.

Examples

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

# Single tool, project scope
npx mewkit migrate cursor

# Multi-tool batch (uses interactive picker if TTY)
npx mewkit migrate

# All 15 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.

init --migrate (one-shot scaffold + export)

mewkit init accepts three migrate-related flags so you can scaffold AND export in a single command.

# Interactive picker after kit unpacks
npx mewkit init --migrate

# Pre-set tools, no picker
npx mewkit init --migrate-to cursor,codex,droid

# All 15 tools
npx mewkit init --migrate-to all

# Global install scope
npx mewkit init --migrate-to cursor --migrate-global

Behavior:

• Migration runs after kit unpacks successfully — failures don't roll back the kit install. If migration fails, init still completes; re-run mewkit migrate to retry.
• Init uses the same orchestrator, registry, and reconciler as the standalone migrate command. Idempotent re-runs work the same way.
• --migrate-to implies --yes (non-interactive), so it's safe to use in CI scripts.