MeowKit

What is MeowKit

MeowKit installs a .claude/ directory that Claude Code reads at session start. It enforces a structured 7-phase workflow with hard gates, TDD, security scanning, and scoped topic-file memory (fixes.md, review-patterns.md, architecture-decisions.md). Zero external dependencies for core workflow.

Homepage: meowkit.dev  ·  Docs: docs.meowkit.dev

Quick Start

MeowKit installs two ways. Pick one per project — running both resolves the same skills and agents twice (mewkit doctor warns when it detects both).

Flat-copy (default, supported)

npx mewkit init

The CLI fetches the latest release from GitHub, prompts for config, and scaffolds .claude/ into your project. Skills resolve as /mk:*, agents as mk:*.

Native plugin (recommended on Claude Code; experimental on Codex)

Installs the mk plugin from the MeowKit marketplace. Skills (/mk:*), agents (mk:*), and hooks all resolve under the plugin; nothing is copied into your project.

Codex support is an experimental projection. MeowKit is fully enforced on Claude Code (real hooks gate behavior); on Codex the capability projection is advisory — hook enforcement is version-gated and not statically guaranteed, so gates deter but do not block. Run mewkit providers codex --lifecycle to see exactly what is enforced vs advisory.

Full semantic parity is a staged, measured track — reported as a parity score. Migration to Codex is default-deny: a runtime: portable skill installs; a runtime: claude-code skill installs only through a tested adapter, otherwise it is skipped with a report reason (never copied unadapted). mewkit providers codex and the migration output print skill parity: N% (portable+adapted ÷ total). The score starts low on purpose — it is the honest roadmap of the parity track, raised by porting skills to runtime: portable. Override the policy with mewkit migrate codex --include-unportable (installs host-bound skills with an EXPERIMENTAL marker).

Parity is machine-verified, and labeled for what it proves. The cross-harness journey (J10) runs a deterministic layer in CI — migration → target validation → route/artifact/denied-token/side-effect oracles — with no model calls. This proves structural parity (the same ask resolves to an equivalent capability or a clean unsupported-capability error, never silent degradation); it is not evidence of semantic/behavioral equivalence, which awaits the model-in-loop layer (a named follow-up). Any parity claim here is either the measured skill-parity score above or this structural check — not an unverified assertion.

Validate a generated Codex project with mewkit validate --target codex <dir> — a read-only post-migration gate that checks the config/hook wiring, that hook wrappers exist + are executable + carry the deny contract, that agent TOMLs parse, and that installed skills declare a supported runtime and carry no host-bound tool tokens. mewkit doctor --providers run inside a migrated project recognizes it and points at this command.

# Claude Code
claude plugin marketplace add ngocsangyem/MeowKit
claude plugin install mk@meowkit

# Codex
codex plugin marketplace add ngocsangyem/MeowKit
codex plugin add mk@meowkit

The plugin distribution is generated by mewkit build-plugin (the plugin/ payload + marketplace.json for both runtimes) and staged into each release.

Setup (required for Python skills)

After installing MeowKit, run:

npx mewkit setup

This creates the Python venv at .claude/skills/.venv, installs pip packages (google-genai, pillow, python-dotenv), and interactively prompts for optional system deps (ImageMagick, FFmpeg, Playwright browsers).

Run once per project. Idempotent — safe to re-run after upgrades.

To verify your environment after setup:

npx mewkit doctor     # Verify environment

Packages

Requirements

• Node.js 20+
• Python 3.9+ (stdlib only, for validation scripts)
• Git

Project Structure

meowkit/
├── .claude/                  Source of truth — agents, skills, rules, hooks
│   ├── agents/               42 specialist agents
│   ├── skills/               128 skills (mk: namespace)
│   ├── rules/                27 enforcement rules
│   ├── hooks/                18 hook scripts — lifecycle hooks + handlers + libraries
│   ├── commands/             27 slash commands
│   ├── modes/                7 behavioral modes
│   ├── memory/               Machine-local topic files (gitignored; scaffolded by `mewkit setup`)
│   ├── scripts/              Python validators + shell utilities
│   └── settings.json
├── tasks/                    Task templates
├── packages/
│   ├── mewkit/               CLI (npm as mewkit)
│   └── landing/              Landing page (meowkit.dev, Nuxt + Tailwind v4)
├── scripts/                  Release automation
├── packages/docs/            Fumadocs documentation
├── CLAUDE.md                 Entry point for Claude Code
├── .releaserc.cjs            Semantic release config
└── .github/workflows/        CI/CD (release, beta, PR validation)

Releasing

See RELEASING.md for the complete release guide — manual steps, CI/CD automation, troubleshooting.

Development

npm install              # Install dependencies
npm run build            # Build both packages
npm test                 # Run tests
npm run lint             # Lint
npm run typecheck        # Type check

License

MIT

Inspiration

• gstack — Skills, review patterns, ship workflow
• antigravity-kit — Clean code standards, vulnerability scanning
• aura-frog — Agent detection, workflow orchestration
• claudekit-engineer — Cook/fix pipelines, release model