klappy · klappy · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-02-02
+
+### Added
+
+- **Claude Code integration** — First-class support for Claude Code:
+  - `oddkit init --claude` — Configure `~/.claude.json` for Claude Code
+  - `oddkit init --all` — Configure both Cursor and Claude Code at once
+  - Auto-detects Claude Code environment and defaults to claude target
+
+- **CLAUDE.md generator** — New command `oddkit claudemd`:
+  - Generates project-level context file for Claude Code
+  - Includes oddkit integration instructions and examples
+  - `--advanced` flag for epistemic mode documentation
+  - Safe append to existing CLAUDE.md files
+
+- **Claude Code hooks** — New command `oddkit hooks`:
+  - Generates `.claude/settings.local.json` with Claude Code hooks
+  - Detects completion claims and reminds about validation
+  - `--minimal` for basic completion detection
+  - `--strict` for preflight reminders before edits
+
+- **Enhanced MCP resources** — Better context for spawned agents:
+  - `oddkit://quickstart` — Essential patterns for subagents
+  - `oddkit://examples` — Common usage patterns with examples
+  - Improved `oddkit://instructions` with spawned agent guidance
+
+- **Documentation** — New `docs/CLAUDE-CODE.md`:
+  - Claude Code specific setup guide
+  - Spawned agent usage patterns
+  - Troubleshooting and configuration reference
+
+### Changed
+
+- **MCP targets are now configurable** — `oddkit init` supports:
+  - `--cursor` — Cursor config (previous default)
+  - `--claude` — Claude Code config
+  - `--project` — Project-local config for either target
+
+- **Updated instructions** — MCP instructions now include spawned agent guidance
+
 ## [0.8.1] - 2026-01-31
 
 ### Changed

diff --git a/docs/CLAUDE-CODE.md b/docs/CLAUDE-CODE.md
@@ -0,0 +1,170 @@
+# oddkit + Claude Code Integration
+
+Get oddkit working with Claude Code in under a minute.
+
+## Quick Setup
+
+### Option 1: One Command (Recommended)
+
+```bash
+npx oddkit init --claude
+```
+
+This configures `~/.claude.json` with the oddkit MCP server.
+
+### Option 2: Configure All Targets
+
+```bash
+npx oddkit init --all
+```
+
+This configures both Cursor (`~/.cursor/mcp.json`) and Claude Code (`~/.claude.json`).
+
+### Option 3: Project-Local Config
+
+```bash
+npx oddkit init --claude --project
+```
+
+This creates `.mcp.json` in your repository for project-specific configuration.
+
+## Verify Setup
+
+After init, restart Claude Code. You should see `oddkit_orchestrate` available as a tool.
+
+Test it by asking Claude Code:
+- "What's in ODD?"
+- "preflight: implement a new feature"
+
+## Generate CLAUDE.md
+
+To add project-level context for Claude Code:
+
+```bash
+npx oddkit claudemd
+```
+
+This creates a `CLAUDE.md` file with oddkit integration instructions that Claude Code will automatically read.
+
+Options:
+- `--print` — Print to stdout only
+- `--force` — Overwrite existing CLAUDE.md
+- `--advanced` — Include advanced epistemic mode documentation
+
+## Configure Hooks (Optional)
+
+Claude Code supports hooks that can integrate with oddkit:
+
+```bash
+npx oddkit hooks
+```
+
+This creates `.claude/settings.local.json` with hooks that:
+- Remind you to run preflight before implementing
+- Detect completion claims and suggest validation
+
+Hook modes:
+- `--minimal` — Just completion detection
+- `--strict` — Validation reminders before file edits
+
+## How It Works
+
+### The oddkit_orchestrate Tool
+
+Claude Code gets access to `oddkit_orchestrate`, a smart router that:
+
+1. **Preflight** — Before implementing, get guidance on what to read
+2. **Librarian** — Answer policy questions with citations
+3. **Validate** — Check if completion claims have required evidence
+4. **Catalog** — Discover available ODD documentation
+
+### Usage Pattern
+
+```
+User: "Implement user authentication"
+Claude: [calls oddkit_orchestrate with "preflight: implement user authentication"]
+Claude: [reads suggested files, notes constraints]
+Claude: [implements the feature]
+Claude: [calls oddkit_orchestrate with "done: implemented auth. Screenshot: auth.png"]
+Claude: [if VERIFIED, reports completion; if NEEDS_ARTIFACTS, provides missing evidence]
+```
+
+### Response Format
+
+oddkit returns JSON with an `assistant_text` field containing a complete, cited answer:
+
+```json
+{
+  "action": "librarian",
+  "assistant_text": "Found relevant documentation...\n\n> Quote from canon...\n\n— canon/definition-of-done.md#DoD",
+  "result": { ... }
+}
+```
+
+Claude Code should use `assistant_text` directly — it's ready for verbatim output.
+
+## Spawned Agents
+
+When Claude Code spawns subagents (via Task tool), they inherit MCP server access. Subagents should:
+
+1. Read `oddkit://quickstart` resource for usage patterns
+2. Always pass `repo_root: "."` when calling tools
+3. Follow the same preflight → implement → validate pattern
+
+## Troubleshooting
+
+### Tool not appearing
+
+1. Restart Claude Code after running `oddkit init --claude`
+2. Check `~/.claude.json` exists and contains oddkit config
+3. Try `npx oddkit init --claude --force` to refresh config
+
+### Preflight not returning results
+
+1. Ensure you're in a git repository
+2. Check baseline is accessible: `npx oddkit librarian -q "test" -r .`
+
+### MCP server errors
+
+1. Ensure Node.js 18+ is installed
+2. Check npm/npx are working: `npx --version`
+3. Try verbose mode: `ODDKIT_DEBUG_MCP=1 npx oddkit-mcp`
+
+## Full Configuration Reference
+
+### MCP Config Location
+
+| Target | Global Path | Project Path |
+|--------|-------------|--------------|
+| Claude Code | `~/.claude.json` | `.mcp.json` |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ODDKIT_BASELINE` | Override baseline repo (git URL or local path) |
+| `ODDKIT_BASELINE_REF` | Pin baseline to specific branch/tag |
+| `ODDKIT_DEV_TOOLS` | Set to `1` to expose all tools (debugging) |
+| `ODDKIT_DEBUG_MCP` | Set to `1` for verbose MCP logging |
+
+### Manual Config
+
+If you prefer manual configuration, add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "oddkit": {
+      "command": "npx",
+      "args": ["--yes", "--package", "github:klappy/oddkit", "oddkit-mcp"]
+    }
+  }
+}
+```
+
+## Next Steps
+
+- Read [docs/MCP.md](MCP.md) for full MCP integration details
+- Read [docs/getting-started/agents.md](getting-started/agents.md) for Epistemic Guide + Scribe setup
+- Visit [klappy.dev/odd](https://klappy.dev/odd) for ODD methodology documentation
diff --git a/docs/MCP.md b/docs/MCP.md
@@ -44,8 +44,14 @@ Use this config to run oddkit as an MCP server via **npx from GitHub** (no npm p
 The easiest way to set up oddkit MCP:
 
 ```bash
-# Global Cursor config (recommended)
-npx oddkit init
+# Claude Code (recommended for Claude Code users)
+npx oddkit init --claude
+
+# Cursor config
+npx oddkit init --cursor
+
+# Configure ALL targets (Cursor + Claude Code)
+npx oddkit init --all
 
 # Project-local config
 npx oddkit init --project
@@ -54,7 +60,13 @@ npx oddkit init --project
 npx oddkit init --print
 ```
 
-This writes config to `~/.cursor/mcp.json` (or `<repo>/.cursor/mcp.json` for `--project`). The `init` command safely merges with existing config—it won't overwrite other MCP servers.
+Config locations:
+- **Claude Code:** `~/.claude.json` (global) or `.mcp.json` (project)
+- **Cursor:** `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)
+
+The `init` command safely merges with existing config—it won't overwrite other MCP servers.
+
+See [CLAUDE-CODE.md](CLAUDE-CODE.md) for Claude Code specific setup and features.
 
 ## Compass Prompts
 
@@ -236,17 +248,26 @@ Use the [Cursor config (long-term)](#cursor-config-long-term-run-from-anywhere)
 
 ### For Claude Code
 
+**Location:** `~/.claude.json` (global) or `.mcp.json` (project-local)
+
 ```json
 {
   "mcpServers": {
     "oddkit": {
       "command": "npx",
-      "args": ["oddkit-mcp"]
+      "args": ["--yes", "--package", "github:klappy/oddkit", "oddkit-mcp"]
     }
   }
 }
 ```
 
+**Recommended:** Use `npx oddkit init --claude` instead of manual setup.
+
+See [CLAUDE-CODE.md](CLAUDE-CODE.md) for:
+- CLAUDE.md generator (`npx oddkit claudemd`)
+- Claude Code hooks (`npx oddkit hooks`)
+- Spawned agent context
+
 ### From local clone
 
 ```json

diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -18,27 +18,45 @@ oddkit has three layers:
 
 ## Quick Links
 
+- [Claude Code Guide](CLAUDE-CODE.md) — Claude Code specific setup
 - [Agents Guide](getting-started/agents.md) — Set up Epistemic Guide + Scribe
 - [Ledger Guide](getting-started/ledger.md) — Capture learnings and decisions
 - [MCP.md](MCP.md) — Full MCP integration details
 - [klappy.dev/odd](https://klappy.dev/odd) — ODD methodology docs
 
 ---
 
+## Claude Code Setup (Recommended)
+
+```bash
+npx oddkit init --claude
+# Restart Claude Code
+```
+
+This writes MCP config to `~/.claude.json`. See [CLAUDE-CODE.md](CLAUDE-CODE.md) for full details.
+
+**Configure both Cursor and Claude Code:**
+
+```bash
+npx oddkit init --all
+```
+
+---
+
 ## Cursor Setup
 
-To use oddkit as an MCP server in Cursor (or Claude Code / Codex), see **[docs/MCP.md](MCP.md)**. You can run oddkit from anywhere via:
+To use oddkit as an MCP server in Cursor, see **[docs/MCP.md](MCP.md)**. You can run oddkit from anywhere via:
 
 ```bash
 npx --yes --package github:klappy/oddkit oddkit-mcp
 ```
 
-## Use in Cursor (recommended)
+## Use in Cursor
 
 ### Option A: One command (global)
 
 ```bash
-npx oddkit init
+npx oddkit init --cursor
 # Restart Cursor if prompted
 ```
 
@@ -47,7 +65,7 @@ This writes MCP config to `~/.cursor/mcp.json` and wires oddkit as a tool.
 ### Option B: Project-local config
 
 ```bash
-npx oddkit init --project
+npx oddkit init --cursor --project
 ```
 
 This writes to `<repo>/.cursor/mcp.json` instead.

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "oddkit",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Agent-first CLI for ODD-governed repos. Epistemic terrain rendering with portable baseline.",
   "type": "module",
   "bin": {