Crux + Claude Code

Claude Code has the deepest Crux integration — full MCP support plus native hooks for automatic session tracking.

Setup

After running ~/.crux/setup.sh, Claude Code integration is automatic:

# Verify MCP server is configured
cat ~/.claude/mcp.json
# Should show "crux" server

# Restart Claude Code to load the server
# Crux tools are now available

What Works

MCP Tools (37 available)

Claude Code can call any Crux MCP tool:

lookup_knowledge — Find relevant knowledge entries
get_session_state — Check current session
update_session — Update working state
get_mode_prompt — Load a specialized mode
validate_script — Run safety validation
log_correction — Record a correction

Native Hooks

Claude Code hooks fire automatically:

Hook	What It Does
SessionStart	Injects mode prompt, session state, pending tasks
PostToolUse	Tracks files touched, logs interactions
UserPromptSubmit	Detects corrections in your messages
Stop	Updates session timestamps, checks TDD compliance

TDD Enforcement

The Stop hook checks TDD compliance:

You modified: scripts/lib/crux_bip.py
Expected test: tests/test_crux_bip.py

STOP — TDD VIOLATION DETECTED
Write tests before proceeding.

Correction Detection

When you correct Claude:

You: "No, use python-jose not PyJWT"

The UserPromptSubmit hook detects this as a correction and logs it. Future sessions know the preference.

Configuration

MCP Server (`~/.claude/mcp.json`)

{
  "mcpServers": {
    "crux": {
      "command": "/path/to/.crux/.venv/bin/python",
      "args": ["-m", "scripts.lib.crux_mcp_server"],
      "env": {
        "CRUX_PROJECT": ".",
        "CRUX_HOME": "/home/you",
        "PYTHONPATH": "/path/to/.crux"
      }
    }
  }
}

Hooks (`~/.claude/settings.local.json`)

Generated by crux adopt. Configures all four hooks.

Workflow

Start session — SessionStart hook injects context
Work normally — PostToolUse tracks files
Make corrections — UserPromptSubmit captures them
End session — Stop hook persists state

Next session picks up where you left off.

Switching Away

# Save state and configure another tool
crux switch cursor

# Your context transfers

Troubleshooting

MCP server not loading

# Check if venv exists
ls ~/.crux/.venv/bin/python

# Reinstall if needed
cd ~/.crux && ./setup.sh

Hooks not firing

# Check settings.local.json exists
cat .claude/settings.local.json

# Re-run adopt if needed
crux adopt