Installation

Prerequisites

• Node.js 24 or later
• Python 3.9 or later. mewkit setup creates a virtualenv at .claude/skills/.venv and pip-installs google-genai, pillow, and python-dotenv, plus any per-skill requirements.txt
• Git installed and configured
• Claude Code installed (claude.ai/code)

Install

npx mewkit init

On a fresh install, mewkit init first asks which toolkits to set up, a multiselect of Claude Code (preselected), Codex, and Cursor, then provisions each: Claude Code generates the .claude/ directory, Codex copies the authored Codex bundle, Cursor installs .claude/ and exports it to .cursor/. Selecting only Codex yields a codex-only project.

Interactive setup

On a fresh install the CLI prompts, in order:

All other settings use fixed defaults: cost tracking enabled, memory enabled, mode set to balanced. Stack detection is not performed. In update mode (an existing .claude/), the toolkit picker is skipped and init just refreshes .claude/.

CLI flags

Skip the interactive prompts with flags:

npx mewkit init --target codex     # Skip the picker, Codex-only toolkit
npx mewkit init --target cursor    # Skip the picker, .claude/ plus export to Cursor
npx mewkit init --force            # Overwrite existing .claude/
npx mewkit init --dry-run          # Preview without writing
npx mewkit init --profile core     # Install a right-sized profile subset

Passing --target (or --migrate) skips the toolkit multiselect and runs that flow directly.

What gets generated

.claude/              What Claude Code reads
├── agents/          Specialist agents for each phase
├── skills/          Domain skills with mk: namespace
├── hooks/           Lifecycle hooks
├── rules/           Enforcement rules
├── scripts/         Python validators
│   └── bin/         Shell utilities
├── modes/           Behavioral modes
└── settings.json    Hook registrations

.meowkit/             Your project's own state
├── config.json      Project configuration, commit this
├── .env             API keys, gitignored, shared by every provider
├── metadata.json    What this install put on disk, and what you have edited since
├── pack-manifest.json  Which packs this release ships
├── harness-inventory.json  Generated registry of .claude/ artifacts
├── memory/          Fix patterns, review patterns, architecture decisions
├── telemetry/       Cost log, trace log
├── state/           Session markers
└── cache/           Derived wiki index, rebuildable

CLAUDE.md             Entry point for Claude Code
.mcp.json.example     Optional MCP server config

The split follows ownership: .claude/ holds what Claude Code itself reads, so settings.json and .mcp.json stay there. Everything MeowKit owns lives in .meowkit/. Only config.json is meant to be committed; the state directories are machine-written and belong in .gitignore (mewkit setup appends them for you).

metadata.json is worth knowing about even though you never edit it. It records what the install wrote and what its contents were, which is how mewkit upgrade can tell a file you edited from one it shipped. Delete it and the next upgrade has no baseline, so it treats every file as untouched.

An install created before these files moved keeps working: readers fall back to the old .claude/ locations, and the next upgrade migrates each one forward.

Verify installation

npx mewkit doctor

This checks: Node.js version, Python version, Git availability, hooks executable, scripts present.

Post-install setup

MCP servers (optional)

Copy .mcp.json.example to .mcp.json and configure servers you need:

cp .mcp.json.example .mcp.json

Available MCP servers: Context7 (docs), Playwright (QA), Sequential Thinking.

Gemini API key (optional)

For mk:multimodal (image/video/audio analysis):

# Add to .meowkit/.env, gitignored, secrets stay local
echo "MEOWKIT_GEMINI_API_KEY=your-key" >> .meowkit/.env

Get a key at aistudio.google.com/apikey.

Troubleshooting

Next steps

After scaffolding, finalize setup:

npx mewkit setup    # Post-scaffold configuration (venv, MCP, env, gitignore)
npx mewkit doctor   # Verify installation

• Quick Start: your first task with MeowKit
• Configuration: customize MeowKit for your project