Configuration

MeowKit is configured through several files:

CLAUDE.md

The entry point Claude reads at session start. Contains:

• Philosophy and core principles
• Workflow phases (Phase 0-6)
• Agent roster with ownership
• Command index
• Model routing table
• Mode definitions
• Memory system description
• Security rules summary

Customize: Add project-specific conventions, adjust mode preferences. Do not modify: Security rules, gate definitions, agent roster structure.

.meowkit.config.json

Project-specific configuration generated by npx mewkit init. Runtime commands prefer the root .meowkit.config.json file and fall back to .claude/meowkit.config.json for older installs:

{
  "$schema": "https://meowkit.dev/schema/config.json",
  "version": "1.0.0",
  "project": { "name": "my-project", "stack": ["node", "react"] },
  "team": { "size": "solo" },
  "tool": { "primary": "claude-code" },
  "mode": { "default": "balanced" },
  "features": { "costTracking": true, "memory": true },
  "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" }
      }
    }
  }
}

Model routing config

modelRouting.providers is user-modifiable and used by npx mewkit migrate.

Key	Purpose
providers.<tool>.default.model	Default model to write only when that target has a verified config surface.
providers.<tool>.tiers.heavy.model	Target model for source model: opus.
providers.<tool>.tiers.balanced.model	Target model for source model: sonnet.
providers.<tool>.tiers.light.model	Target model for source model: haiku.
reasoningEffort	Optional Codex reasoning effort. Written as model_reasoning_effort for Codex agents.

If a provider or tier is missing, migration omits the target model field and lets the target coding agent use its own default. MeowKit does not hardcode target model IDs.

.claude/settings.json

Hook registrations and permission allowlists. See Hooks for details.

dispatch.cjs entries (v2.3.0)

The following entries were added in v2.3.0 to route events to dispatch.cjs. They run alongside the existing shell hook entries — both shell and Node.js hooks fire on the same events:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [
        { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch.cjs\" SessionStart", "timeout": 10 }
      ]
    }],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch.cjs\" PostToolUse \"Edit|Write\"", "timeout": 40 }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch.cjs\" PostToolUse Bash", "timeout": 15 }
        ]
      }
    ],
    "Stop": [{
      "hooks": [
        { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch.cjs\" Stop", "timeout": 10 }
      ]
    }],
    "UserPromptSubmit": [{
      "hooks": [
        { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch.cjs\" UserPromptSubmit", "timeout": 10 }
      ]
    }]
  }
}

PostToolUse Edit|Write has both post-write.sh (shell, security scan) and dispatch.cjs entries. Both fire independently on every file write.

Environment variables (v2.3.0+)

See Environment Variables below for the complete reference.

.claude/.env File

MeowKit loads .claude/.env automatically at session start. This is the recommended way to set project-level env vars (API keys, config overrides) without polluting your shell profile.

How it works:

1. project-context-loader.sh (SessionStart) sources .claude/.env into the shell environment → all shell hooks inherit it
2. dispatch.cjs parses .claude/.env into process.env → all Node.js handlers inherit it
3. mk:multimodal Python scripts have their own .env loading (predates centralized loader)

Precedence: Shell exports (export VAR=x) always win. .env vars only apply when the var is not already set. This means you can override .env per-session with export.

Setup:

cp .claude/.env.example .claude/.env
# Edit .claude/.env with your values

Security: .env is gitignored by default. Never commit API keys. The privacy-block.sh hook blocks Claude from reading .env files directly — the dotenv loader is the only authorized reader.

Template: See .claude/.env.example for all supported variables with descriptions.

Rules

19 rule files in .claude/rules/, loaded in priority order:

Priority	Rule	Purpose
1	security-rules.md	Blocked patterns: secrets, any, SQL injection
2	injection-rules.md	10 prompt injection defense rules
3	gate-rules.md	Gate 1 + Gate 2 hard stops
4	harness-rules.md	Harness generator/evaluator discipline
5	rubric-rules.md	Evaluator rubric calibration
6	core-behaviors.md	Mandatory operating behaviors
7	tdd-rules.md	Opt-in TDD enforcement
8	agent-conduct.md	Naming, responses, context ordering, search-before-building
9	development-rules.md	Skill activation, file management, code quality, git safety
10	step-file-rules.md	Step-file workflow execution
11	model-selection-rules.md	Task type → model tier routing
12	skill-authoring-rules.md	Skill metadata, state, and size discipline
13	scale-adaptive-rules.md	Domain-complexity routing
14	risk-checklist.md	Horizontal risk flags
15	parallel-execution-rules.md	Worktree isolation and team coordination
16	orchestration-rules.md	Subagent delegation and file ownership
17	post-phase-delegation.md	Project-manager fire points

Modes

Mode	Gates	Security	Use for
default	Both	Full	Most work
strict	Both (no WARN)	Every file	Production, auth, payments
fast	Both (WARNs auto-ack)	BLOCK only	Prototypes
architect	N/A	N/A	Design-only sessions
audit	N/A	Comprehensive	Security reviews
document	N/A	N/A	Doc sprints
cost-saver	Both (WARNs auto-ack)	BLOCK only	High-volume routine

Environment Variables

All MEOWKIT_* env vars. Set in your shell profile (~/.zshrc, ~/.bashrc) or per-session via export.

Core

Variable	Default	Purpose	When to use
MEOWKIT_TDD	off	Enable strict TDD enforcement (RED-phase gate). Values: 1, true, on, enabled	Production-quality code, payment/auth features. Opt-in — most users leave this off.
MEOWKIT_MODEL_HINT	(none)	Fallback model ID for tier detection when SessionStart stdin lacks model field	Only if model-detector.cjs shows "not detected". Most users don't need this — stdin auto-detection is primary since v2.3.0.
MEOW_HOOK_PROFILE	standard	Hook execution profile. standard = normal, fast = skip non-critical hooks (post-session, learning-observer, pre-ship), strict = all hooks enabled	fast for rapid iteration/spike work. strict for production sessions needing full memory capture.
CLAUDE_CODE_FORK_SUBAGENT	1 (set in settings.json env block by default since v2.8.3)	Enables Claude Code's context: fork semantics so the 16 mk:jira-* thin skills fork into their matching agents.	Leave default. Unset only when explicitly debugging fork-mode behavior.

Jira

The mk:jira-* family (router + 16 leaves added in v2.8.3) is driven by three MEOW_JIRA_* env vars in .claude/.env (gitignored). The wrapper script scripts/jira-as.sh translates them to jira-as's native JIRA_* names per call.

Naming exception: these vars use the legacy MEOW_* prefix (one-off exception to the modern MEOWKIT_* convention) per migration directive. The upstream JIRA-Assistant-Skills README also mentions JIRA_PROFILE — that is a plugin-layer concern, NOT consumed by jira-as or mk:jira.

Variable	Default	Purpose	Where to set
MEOW_JIRA_API_TOKEN	(required)	Atlassian Cloud API token. Get from https://id.atlassian.com/manage-profile/security/api-tokens.	.claude/.env
MEOW_JIRA_EMAIL	(required)	Atlassian account email.	.claude/.env
MEOW_JIRA_SITE_URL	(required)	e.g. https://your-company.atlassian.net.	.claude/.env
JIRA_OUTPUT	json (set by wrapper)	Default output format for jira-as.	Override per-call: JIRA_OUTPUT=text bash scripts/jira-as.sh ...
JIRA_MOCK_MODE	(unset)	When set to true, agents surface **[MOCK MODE]** in output headers; intelligence agents avoid live writes.	Sandbox / CI testing.

The SessionStart hook jira-env-loader.sh validates .claude/.env presence + the 3 required keys. It emits [mk:jira] env OK / [mk:jira] <KEY> missing to the status line.

Setup (one-time):

npx mewkit setup           # auto-installs jira-as into .claude/skills/.venv
cp .claude/.env.example .claude/.env
# edit MEOW_JIRA_API_TOKEN, MEOW_JIRA_EMAIL, MEOW_JIRA_SITE_URL

Harness (Autonomous Build Pipeline)

Variable	Default	Purpose	When to use
MEOWKIT_AUTOBUILD_MODE	(auto-detected)	Override scaffolding density: MINIMAL (Haiku), FULL (Sonnet/Opus 4.5), LEAN (Opus 4.6+)	When auto-detection picks wrong density. LEAN skips contract negotiation; MINIMAL short-circuits to /cook. Does NOT bypass gates.
MEOWKIT_BUDGET_WARN	30	USD threshold for budget warning message	Lower for cost-conscious sessions, higher for long research runs.
MEOWKIT_BUDGET_BLOCK	100	USD threshold for hard session block	Emergency brake. Session halts at this amount.
MEOWKIT_BUDGET_CAP	(none)	User override for hard block — can be lower OR higher than BUDGET_BLOCK	Set MEOWKIT_BUDGET_CAP=200 for intentional high-budget harness runs. Set MEOWKIT_BUDGET_CAP=15 for tight budgets.
MEOWKIT_RUN_ID	current	Harness run identifier for trace and budget tracking	Set automatically by mk:autobuild step-00. Don't set manually unless resuming.

Memory

Memory is loaded on-demand by consumer skills via Read calls — there is no per-turn auto-injection pipeline (removed in v2.4.1). See Memory System for details.

Hook Controls

Variable	Default	Purpose	When to use
MEOWKIT_BUILD_VERIFY	on	Set off to skip post-write compile/lint checks	Disable during bulk file generation where per-file verification is too slow.
MEOWKIT_LOOP_DETECT	on	Set off to skip edit-count loop detection	Disable during intentional multi-pass refactoring.
MEOWKIT_PRECOMPLETION	on	Set off to skip pre-completion verification check	Disable if the check blocks session exit incorrectly.
MEOWKIT_TDD_FLAG_DETECTOR	on	Set off to disable --tdd flag detection in user prompts	Disable if --tdd in your prompt text triggers TDD unintentionally.

Examples

Production session with TDD and strict hooks:

export MEOWKIT_TDD=1
export MEOW_HOOK_PROFILE=strict

Quick prototyping session:

export MEOW_HOOK_PROFILE=fast
export MEOWKIT_BUILD_VERIFY=off

High-budget harness run on Opus 4.6:

export MEOWKIT_BUDGET_CAP=200
# MEOWKIT_AUTOBUILD_MODE auto-detects LEAN for Opus 4.6