wheeler: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this codebase is

Wheeler is a Python package that turns Claude Code into a provenance-tracked research assistant. It is not an agent framework: there is no orchestration layer. Claude Code is the orchestrator; Wheeler provides (a) MCP tools that mutate a Neo4j knowledge graph, and (b) /wh:* slash commands that act as mode-restricted system prompts. Everything runs locally on a Max subscription via claude -p subprocess. No API keys are used, ever.

Version is 0.15.0. 3040+ tests (see the suite for the current count), 53 MCP tools across the four split servers. The legacy monolith has been removed.

Wheeler now runs on two agent hosts, Claude Code and OpenAI Codex, and ships as a plugin named wh rather than by copying files into ~/.claude/. The act bodies are served over MCP (get_act) so they exist in exactly one place; each host gets generated SKILL.md stubs. See "Multi-host distribution" below.

Commands

# Environment (Python 3.11+).  uv is the primary workflow; the pip path
# remains supported for contributors without uv installed.
uv sync --extra dev            # creates .venv/, installs from uv.lock
# or:
source .venv/bin/activate
pip install -e ".[test]"       # core + test deps (fastembed + numpy are in core)
pip install -e ".[dev]"        # full toolchain: tests + ruff + mypy + build
pip install -e ".[search]"     # legacy no-op (fastembed+numpy already in core)

# Tests
python -m pytest tests/ -q                                   # full suite, quiet
python -m pytest tests/test_merge.py -v                      # one file
python -m pytest tests/test_merge.py::TestExecuteMerge -v    # one class
python -m pytest tests/ -k "consistency"                     # by keyword
python -m pytest tests/e2e/ -v                               # e2e, needs running Neo4j
python -m pytest tests/e2e/test_graph_first_acts.py -v       # graph-first act workflows
python -m pytest tests/e2e/test_plan_lifecycle.py -v         # plan lifecycle + triple-write

# E2E test philosophy: simulate the actual act workflow against live Neo4j.
# Each test walks through the exact tool-call sequence an act prescribes:
#   1. WRITE to graph (add_plan, ensure_artifact, add_finding, link_nodes)
#   2. READ back via the same query the act uses (query_plans, query_notes)
#   3. Verify graph state with direct Cypher (status, relationships, properties)
#   4. Verify triple-write artifacts on disk (knowledge/*.json, synthesis/*.md)
# This catches drift between what the act prompt says and what the graph
# actually stores. If an act says "call query_plans(status=approved)" but
# the query returns nothing because the status enum changed, the e2e test
# fails. Unit tests with FakeBackend can't catch that.
#
# TRAP when adding a live-Neo4j test late in the suite: graph_tools._get_backend()
# caches ONE module-level backend for the whole process, and each backend owns its
# own circuit breaker. Earlier tests push MagicMock values through that shared
# instance, which trips the breaker OPEN for 60s, so a live test placed after them
# fails with `circuit_open` while passing in isolation. Clear `_backend_instance`
# and call `invalidate_async_driver()` in your fixture's setup AND teardown.
# See tests/test_triple_write_project_root.py for the pattern.
#
# Also: the suite is sensitive to concurrent writers on one Neo4j. A red full-suite
# run in the asta/llmsr integration tests is worth re-running before treating it as
# a regression; those tests write and read back, so a second writer looks like a bug.

# Lint + type check (run by pre-commit hook)
.venv/bin/ruff check wheeler/
.venv/bin/mypy wheeler/ --ignore-missing-imports

# Git hooks (strongly recommended — block commits with API key leaks, broken tests, lint errors)
wh hooks install    # copies .githooks/pre-commit + pre-push into .git/hooks/
wh hooks test       # runs pre-commit checks without committing

# Headless Claude runs (for background tasks)
wh queue "prompt"   # sonnet, 10 turns, structured JSON log to .logs/
wh quick "prompt"   # haiku, 3 turns, one-shot
wh dream            # graph consolidation (promotes tiers, detects communities, flags stale)

# MCP servers (launched by Claude Code via .mcp.json — not typically invoked by hand)
python -m wheeler.mcp_core         # split: health/context/search/cypher/schema (12)
python -m wheeler.mcp_query        # split: read-only query_* (11)
python -m wheeler.mcp_mutations    # split: add_*, link, unlink, delete, merge, update (18)
python -m wheeler.mcp_ops          # split: staleness, citations, consistency, ops (10)