---
title: Configuration
description: All MeowKit configuration options across CLAUDE.md, settings.json, and config files.
persona: C
---

# 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:

```json
{
  "$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](/reference/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:

```json
{
  "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](#environment-variables) below for the complete reference.

## .claude/.env File {#dotenv}

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:**
```bash
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):**

```bash
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_HARNESS_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:harness` step-00. Don't set manually unless resuming. |

### Conversation Summary Cache

| Variable | Default | Purpose | When to use |
|----------|---------|---------|-------------|
| `MEOWKIT_SUMMARY_CACHE` | `on` | Enable/disable conversation summary. Set `off` to disable. | Disable if using a custom context management strategy or to save ~$0.01–0.02/session. |
| `MEOWKIT_SUMMARY_THRESHOLD` | `20480` | Min transcript bytes before summarization triggers | Increase for short sessions that don't need summaries. |
| `MEOWKIT_SUMMARY_TURN_GAP` | `30` | Min JSONL events between summaries (≈ 3–6 turns) | Lower for more frequent summaries in long sessions. |
| `MEOWKIT_SUMMARY_GROWTH_DELTA` | `5120` | Min transcript growth bytes between summaries | Pair with TURN_GAP — both are OR conditions. |
| `MEOWKIT_SUMMARY_BUDGET_SEC` | `180` | Background worker timeout for `claude -p` summarization | Increase on slow networks. |
| `MEOWKIT_SUMMARY_DEBUG` | *(none)* | Set `1` for verbose stderr from summary hook | Debugging summary issues only. |

### 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](/guide/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:**
```bash
export MEOWKIT_TDD=1
export MEOW_HOOK_PROFILE=strict
```

**Quick prototyping session:**
```bash
export MEOW_HOOK_PROFILE=fast
export MEOWKIT_BUILD_VERIFY=off
```

**High-budget harness run on Opus 4.6:**
```bash
export MEOWKIT_BUDGET_CAP=200
# MEOWKIT_HARNESS_MODE auto-detects LEAN for Opus 4.6
```

**Disable conversation summaries:**
```bash
export MEOWKIT_SUMMARY_CACHE=off
```
