Claude-Code Boilerplate Framework

Defines how we work, not what we're building. If a rule doesn't change behavior, it doesn't belong here.

Global defaults: ~/.claude/CLAUDE.md — communication style, platform (Windows/PowerShell), Python toolchain (uv), git conventions. Loaded before this file every session; project rules override.

What Are You Building?

Key Commands

# Trigger.dev — start local dev runner
npx trigger.dev@latest dev

# Re-run first-time setup (e.g. fresh clone)
rm -f .claude/.setup-complete && bash .claude/hooks/setup.sh

# Install a single component (modular — no marker needed)
bash .claude/hooks/install/cli-firecrawl.sh      # example: just firecrawl CLI
bash .claude/hooks/install/plugin-caveman.sh     # example: just caveman plugin
bash .claude/hooks/install/tool-lightrag.sh      # example: just LightRAG

# Reinstall context-monitor statusline
npx claude-code-templates@latest --setting statusline/context-monitor

# Browser automation (WAT Tools layer example)
node tools/playwright.js screenshot https://example.com

# FFmpeg — video/audio processing
node tools/ffmpeg.js probe video.mp4                              # inspect metadata
node tools/ffmpeg.js trim input.mp4 --start 00:00:30 --end 00:01:00
node tools/ffmpeg.js thumbnail input.mp4 --at 00:00:10 --width 1280
node tools/ffmpeg.js extract-audio input.mp4 --format mp3
node tools/ffmpeg.js transcode input.avi --format mp4 --resolution 1280x720
node tools/ffmpeg.js concat a.mp4 b.mp4 --output merged.mp4

# /generate — AI image/video generation (Kie AI), output gallery
node generations/gallery-server.mjs                # → http://localhost:3737 (or VS Code Run & Debug → "Generate Gallery")

# Supabase CLI — local dev, migrations, type generation
supabase login                                                     # one-time browser OAuth
supabase init                                                      # init project (first time)
supabase start                                                     # start local stack (Docker required)
supabase db push                                                   # push migrations to remote
supabase migration new <name>                                      # create a new migration file
supabase gen types typescript --project-id <id> > types/db.ts     # generate TypeScript types
supabase functions deploy <function-name>                          # deploy edge function
supabase stop                                                      # stop local stack

# NotebookLM — authenticate and create research notebook
notebooklm login
notebooklm create "Research Project" --use
notebooklm source add --url "https://example.com"
notebooklm chat ask "Summarize this"
notebooklm audio create && notebooklm audio status <task-id>

# Upgrade NotebookLM CLI
uv tool upgrade notebooklm-py

# AutoResearch — autonomous ML experiments
cd tools/autoresearch
uv run prepare.py              # One-time data prep (~2 min)
uv run train.py                # Test baseline run (~5 min)
# Then use /autoresearch skill to start autonomous research loop

# LightRAG — graph-based RAG (see LightRAG Server Setup section below for full start options)
cd tools/lightrag-plus && UV_NATIVE_TLS=true uv sync --all-extras && cp .env.example .env  # First-time setup

# OpenSpace — self-evolving skill system (CLI first, MCP backup)
# Git submodule — auto-syncs with upstream every session via openspace-sync.sh hook
cd tools/openspace
uv pip install -e ".[windows]"             # Install OpenSpace (done by setup.sh; use linux/macos on those platforms)

# CLI (primary — token-free execution)
openspace --query "Create a monitoring dashboard for Docker containers"
openspace-download-skill <skill_id>      # Download from cloud
openspace-upload-skill /path/to/skill/dir # Upload to cloud (requires OPENSPACE_API_KEY)

# Seed local skills into the dashboard tree (SQLite) without a task run
# Lean default = repo .claude/skills + tools/openspace/showcase/skills. Seeder lives in tools/openspace_overrides/ (OUTSIDE the submodule).
tools/openspace/.venv/Scripts/python.exe tools/openspace_overrides/seed_openspace_skills.py
tools/openspace/.venv/Scripts/python.exe tools/openspace_overrides/seed_openspace_skills.py --include-global  # + global-only ~/.claude/skills (dedups vs repo by name)
# Runtime discovery dir is OPENSPACE_HOST_SKILL_DIRS (NATIVE paths — /c/... git-bash paths fail on Windows Python)

# MCP (backup — use when CLI output insufficient or need structured results)
# Search: mcp__openspace__search_skills (no CLI equivalent)
# Use mcp__openspace__* tools via ToolSearch when CLI doesn't meet needs

# Submodule updates (automatic via stop hook, or manual)
git submodule update --remote tools/openspace  # Manual: pull latest from upstream

# Graphify — one-time per repo (must build before /graphify or graphify-mcp work)
graphify .                                          # Parse codebase → graphify-out/graph.json
graphify query "what calls authMiddleware?"         # Query without MCP

# Session management
/roast <idea>                     # Pressure-test idea before building (5-persona council)
/session-handoff                  # Structured wrap-up before /clear — chat-only

# Caveman — token compression (75% reduction on responses, 46% on memory files)
/caveman                          # Activate compression mode (lite/full/ultra)
/caveman-stats                    # Show session token usage + savings
/caveman-compress memory-*.md     # Shrink memory files by ~46%
/caveman-commit                   # Terse commit messages (≤50 chars)
/caveman-review                   # Single-line PR comments
/cavecrew                         # Compressed subagents (60% fewer tokens)

# Dashboard (optional — requires Node.js ≥ 20)
# Press F5 → "OpenSpace Dashboard (Full Stack)" — or see tools/openspace/README.md

MCP credential gotcha: .mcp.json ${VAR} substitution reads from the OS process environment, not .env. On a fresh machine, run setx VAR_NAME "value" (Windows) or export VAR_NAME=value (Unix) in your terminal before starting Claude Code.

First-Time Setup

# 1. Install dependencies
npm install

# 2. Run initial setup (hooks, skills, permissions, CLI tools, git submodules)
bash .claude/hooks/setup.sh
# Installs: marketplace plugins (ui-ux-pro-max, impeccable, codex, gemini, cli-anything, caveman, context-mode, claude-mem, claude-video, ponytail, mattpocock-skills)
# Step 7a:  Apify agent skills (5 skills from apify/agent-skills marketplace) with 30-sec timeout protection; displays manual /plugin install commands if timeout/failure occurs
# Step 7b:  Caveman plugin (token compression — 75% response reduction, 46% memory file reduction)
# Step 7c:  Context Mode plugin (98% context reduction via sandboxing; statusline shows session/total savings + efficiency %); auto-installs better-sqlite3 with NODE_TLS_REJECT_UNAUTHORIZED=0 (corporate SSL proxy fix) for FTS5 session continuity
# Step 7d-pre: Bun runtime (required by claude-mem worker for web viewer + MCP search; also 3-5x faster context-mode sandbox); Windows: powershell -c "irm bun.sh/install.ps1 | iex"; Unix: curl -fsSL https://bun.sh/install | bash
# Step 7d:  Claude-Mem plugin (persistent memory across sessions; context survives session end/reconnect; web viewer at http://localhost:37777; requires Bun)
# Step 7e:  claude-obsidian plugin (Obsidian AI second brain — Karpathy LLM Wiki pattern; run /wiki to scaffold vault after install)
# Step 7f:  higgsfield plugin (CLI + plugin from higgsfield-ai/skills; installs @higgsfield/cli globally + higgsfield@higgsfield-ai plugin; auth: higgsfield auth login)
# Step 8:   Project skills with cross-platform path detection (Windows $USERPROFILE fallback, Unix-style path conversion); creates destination directory; verifies each copy succeeded
# Step 9:   npm install (all package.json deps: react, react-dom, @types/react, @splinetool/react-spline, @splinetool/runtime, Playwright) + Playwright Chromium browser
# Step 10:  skillui, firecrawl-cli, codex-cli, gemini-cli, notebooklm-py[browser], codeburn, browser-harness, designlang, kie-cli (@felores/kie-cli)
# Step 11:  alpaca CLI (go install or brew — see cli-alpaca.sh; auth: alpaca profile login or env vars)
# Step 11:  autoresearch dependencies in tools/autoresearch/ (via uv sync)
# Step 12:  lightrag dependencies in tools/lightrag-plus/ (via uv sync); auto-creates tools/lightrag-plus/.env from .env.example if missing (so EMBEDDING_BINDING_HOST is set on first boot); auto-runs provision.py if .env exists (idempotent — skips if no credentials)
# Step 12a: Ollama install + llama3.2 pull (local LLM for LightRAG; Windows: shows winget command, Unix: auto-installs)
# Step 13:  openspace submodule initialization + uv pip install -e ".[<platform>]" (windows/linux/macos extras; avoids uv sync cross-version pyatspi resolution failure) + fastembed (local BAAI/bge-small-en-v1.5 fallback for semantic tool search) + dashboard frontend npm install + npm run build (builds dist/ so backend at port 3789 serves full UI immediately on fresh clone) + .env port alignment (3888 → 3789 to match package.json)
# Step 14:  Obsidian app (winget/brew/flatpak — skips if already installed), vault/ scaffold (private/ dirs + git init — skips if vault already exists), MCPVault MCP registered at user scope (filesystem-based, no Obsidian app required for Claude access)

# 3. Configure MCP credentials
cp .claude/settings.local.json.example .claude/settings.local.json
# Edit settings.local.json and add your API keys (see __activation_guide inside)

# 4. Add API keys to .env
cp .env.example .env
# Edit .env and fill in required keys
# Note: OpenSpace paths (OPENSPACE_HOST_SKILL_DIRS, OPENSPACE_WORKSPACE) are
# auto-configured by setup.sh for your platform — no manual editing needed

# 5. Restart Claude Code to activate MCP servers

First run check:

# If setup.sh was already run, you'll see:
cat .claude/.setup-complete

Core Philosophy: WAT Framework

Workflows → Agents (Claude) → Tools

AI chained through 5 steps at 90% accuracy = 59% success. Offload execution to deterministic scripts in tools/; keep Claude focused on orchestration. Full details: agent-instructions.md

Project Structure

CLAUDE.md                     ← You are here (routing only)
.claude/
  rules/                      ← Auto-loaded every session (all .md files)
  agents/                     ← Custom sub-agent definitions
  skills/                     ← Project skills (<name>/SKILL.md) — setup.sh installs to ~/.claude/skills/
  hooks/                      ← Lifecycle shell scripts (Stop, PostToolUse, pre-commit)
    install/                  ← Modular install scripts — one per plugin/CLI/tool/skill; run standalone or via setup.sh
      lib.sh                  ← Shared helpers (_timeout, _is_windows, _user_home, _install_plugin, _install_skill)
      sys-*.sh                ← System prerequisites (python, node, uvx, bun, env, npm-deps, pre-commit, github-cli)
      plugin-*.sh             ← Claude plugins (ui-ux-pro-max, impeccable, caveman, context-mode, claude-mem, claude-video…)
      skill-apify-*.sh        ← Apify marketplace skills (ultimate-scraper, actor-development, actorization…)
      skills-project.sh       ← Copies .claude/skills/* → ~/.claude/skills/
      cli-*.sh                ← Global CLI tools (firecrawl, codex, gemini, notebooklm, codeburn, browser-harness, kie…)
      tool-*.sh               ← Heavy tools (autoresearch, lightrag, ollama, openspace, graphify)
      auth-reminders.sh       ← Prints one-time manual auth steps (NotebookLM, Trigger, Google, GitHub…)
  scripts/                    ← Utility scripts (statusline, context monitor)
  docs/                       ← Reference docs
  settings.local.json         ← Machine-local credentials + permissions (gitignored)
  settings.local.json.example ← Template: all keys cleared + activation guide per MCP server
.mcp.json                     ← MCP server definitions (version-controlled)
.env / .env.example           ← API keys (gitignored — never commit)
tools/                        ← Deterministic execution scripts (Python/Node)
  playwright.js               ← Browser automation CLI wrapper
  ffmpeg.js                   ← FFmpeg video/audio processing CLI wrapper
  autoresearch/               ← Autonomous ML research (prepare.py, train.py, program.md)
  lightrag-plus/              ← LightRAG Plus (graph-based RAG with multimodal + multi-backend support)
    src/                      ← Plus implementation
      config.py               ← Environment config + feature flags
      lightrag_plus.py        ← Main wrapper class
      embedders/              ← OpenAI (text-only) + Gemini (multimodal) embeddings
      adapters/               ← Supabase + Pinecone vector mirrors (optional)
      ingestors/              ← Multimodal preprocessing (images, video, audio)
    schema/                   ← Backend setup scripts
      supabase_schema.sql     ← Supabase table definitions
    provision.py              ← Auto-provision Supabase schema + Pinecone index (reads .env flags, idempotent)
    check_update.py           ← Check/apply lightrag-hku updates (PyPI diff, pin bump, verify, smoke test)
    setup_backends.py         ← Backend connection validation script
    pyproject.toml            ← Dependencies (lightrag-hku + server + Plus deps)
    uv.lock                   ← Dependency lockfile
    .python-version           ← Pins 3.12 (newer Python has no pyiceberg wheel — would need MSVC to build from source)
    README.md                 ← Full LightRAG Plus documentation
    .env                      ← Server config + API keys (gitignored)
    .env.example              ← Configuration template with all options
    .gitignore                ← Excludes .env, logs, rag_storage, build artifacts
    tests/                    ← Integration tests (35 tests, 7 backend scenarios)
      conftest.py             ← SSL + env fixtures
      test_integration.py     ← Parametrized backend tests
      fixtures/               ← Sample media files
    start_server.bat          ← Windows quick launcher
    .venv/                    ← Virtual environment (gitignored)
    rag_storage/              ← Knowledge graph data (gitignored, auto-created)
  openspace_overrides/        ← ALL non-submodule OpenSpace wrappers/patches live here (survives `git submodule update --remote`)
    seed_openspace_skills.py  ← Seeds local skills into the OpenSpace dashboard tree (repo + showcase; --include-global optional)
    dashboard_server_patched.py ← Runtime monkeypatch entrypoint for openspace.entrypoints.dashboard.server (fixes bugs w/o editing the submodule)
  openspace/                  ← Self-evolving skill system (git submodule — auto-syncs with upstream)
    openspace/                ← Core Python package
    pyproject.toml            ← Dependencies (litellm, anthropic, openai, etc.)
    README.md                 ← Full OpenSpace documentation
    frontend/                 ← Dashboard UI (optional, requires Node.js ≥ 20)
    gdpval_bench/             ← Benchmark experiments & results
    showcase/                 ← Example projects built with OpenSpace
    .openspace/               ← Skill database + embeddings cache
    logs/                     ← Execution logs & recordings
workflows/                    ← Markdown SOPs defining automation tasks
src/trigger/                  ← Trigger.dev TypeScript task files
brand_assets/                 ← Logos, color guides, design tokens
docs/                         ← Project-level documentation
generations/                   ← Media library for /generate — flat output + gallery
  README.md                    ← Layout, gallery server usage, sidecar log format
  gallery.html                 ← Gallery page (served, not opened as file://)
  gallery-server.mjs           ← Zero-dep Node server: GET /api/media + static file serving (localhost:3737)
  styles.json                  ← Reusable style presets (name, prompt, refs) — editable via gallery Styles panel
  refs/                        ← Reference images (logos, faces, style shots) passed into API calls
  {name}.{ext} + {name}.json   ← Generated media, flat, no subfolders — each with a sidecar log
vault/                        ← Obsidian wiki vault (dual-layer)
  wiki/                       ← SHARED: gittracked — boilerplate architecture, integrations, ADRs
  private/                    ← USER: gitignored — sessions, projects, agent logs (per-user)
  .raw/                       ← gitignored — source drops for ingestion
  CLAUDE.md                   ← vault schema and cross-project referencing rules
.tmp/                         ← Scratch space — disposable

Plugins (Enabled)

Disabled Claude plugins (MCP servers for pinecone/supabase are still active — see MCP Servers table): pinecone, supabase, plugin-dev, designlang (source repo deleted — CLI + MCP still active) — enable in .claude/settings.json → enabledPlugins.

Skills (Slash Commands)

Built-in:

Project skills (source: .claude/skills/ — installed by setup.sh):

Superpowers skills auto-trigger based on context (brainstorming, TDD, debugging, code review, planning, subagents, git worktrees). No manual invoke needed.

Additional auto-trigger rules:

• /roast — invoke before any significant feature or product build when the idea is unvalidated. Fire on: "I'm thinking of building X", "what do you think of this idea?", "should I build this?", "pressure-test this", "roast this". Do not skip just because the user seems excited — sycophancy is the failure mode.
• /session-handoff — invoke when user says "wrap up", "hand off", "summarize before I clear", "session handoff", or is about to /clear. Also invoke proactively when context approaches ~250K tokens without a handoff having been run.
• /auto-stage-commit — invoke when user says "commit", "stage this", "let's commit", or shows intent to commit changes. Outputs the ready-to-run git commit command; does not execute it.

Add skills: create <name>/SKILL.md in .claude/skills/ → re-run setup.sh or restart Claude Code.

MCP Servers

Defined in .mcp.json. Add credentials to .env.

Requires uvx: google-workspace-mcp, alpaca, and notebooklm-mcp use uvx. Install: curl -LsSf https://astral.sh/uv/install.sh | sh

Setup: Copy .claude/settings.local.json.example → .claude/settings.local.json. The __activation_guide inside lists where to get each credential.

LightRAG Server Setup

Graph-based RAG with multimodal support. See tools/lightrag-plus/README.md.

Quick start:

cd tools/lightrag-plus && UV_NATIVE_TLS=true uv sync --all-extras && cp .env.example .env
# Add OPENAI_API_KEY (+ SUPABASE_MANAGEMENT_TOKEN if ENABLE_SUPABASE=true) to .env, then:
uv run python provision.py          # Auto-creates schema/index if backends enabled (idempotent)
uv run python check_update.py      # Check for lightrag-hku updates (add --upgrade to apply)
uv run python src/server.py --port 9621 --working-dir ./rag_storage
# Or: Press F5 → "LightRAG Server" (VSCode) / run start_server.bat — both use src/server.py automatically
# LLM_TIMEOUT=1800 + EMBEDDING_TIMEOUT=60 in .env extend Ollama timeouts (defaults 180s/30s are too short for large chunks; 1800s required on slow hardware)
# EMBEDDING_BINDING_HOST in .env fixes the LLM_BINDING_HOST bleed-into-OpenAI-embedding bug (--embedding-binding-host CLI flag removed in newer lightrag-hku)

LightRAGPlus server (src/server.py) vs vanilla server:

Extra endpoints added by src/server.py:

• GET /api/plus/status — backend config + health check
• POST /api/plus/insert-media — image/audio/video → cloud backends only (requires MULTIMODAL_MODE=advanced + EMBEDDING_PROVIDER=gemini)

Known gotcha — embedding 404: LLM_BINDING_HOST=http://localhost:11434 (Ollama) bleeds into OpenAI embedding calls via get_default_host("openai"). Fix: EMBEDDING_BINDING_HOST=https://api.openai.com/v1 in .env (already set). The --embedding-binding-host CLI flag was removed in newer lightrag-hku — env var is the only fix.

Running integration tests (Windows):

# Step 1: sync venv once (do NOT use `uv run pytest` — it re-syncs on every call and hits Windows file locks)
cd tools/lightrag-plus && UV_NATIVE_TLS=true uv sync --all-extras

# Step 2: run tests directly via venv python (repeatable, no re-sync)
.venv\Scripts\python.exe -m pytest tests/test_integration.py -v

# If uv sync fails with "Access is denied" or missing RECORD files — self-heal first:
Remove-Item -Force -Recurse .venv\Lib\site-packages\regex-*.dist-info -ErrorAction SilentlyContinue
Remove-Item -Force -Recurse .venv\Lib\site-packages\proto_plus-*.dist-info -ErrorAction SilentlyContinue
UV_NATIVE_TLS=true uv sync --all-extras

Access: Web UI + API Docs

OpenSpace Integration Tests

Tests live at tests/openspace/ (outside the submodule — preserves auto-sync). Three tiers: Tier 1 no key, Tier 2 any LLM key, Tier 3 OPENSPACE_API_KEY.

# Step 1: install pytest into openspace venv (one-time)
cd tools/openspace && uv pip install pytest pytest-asyncio python-dotenv

# Step 2: run from project root (repeatable)
cd C:\GIT\Claude_Code_Boilerplate_Framework
tools\openspace\.venv\Scripts\python.exe -m pytest tests\openspace\ -v

# Tier 1 only (no API key needed):
tools\openspace\.venv\Scripts\python.exe -m pytest tests\openspace\ -v -k "not TestOpenSpaceInit and not TestCloudRegistry"

Tier 2 tests (TestOpenSpaceInit) read LLM key from tools/openspace/.env or OS env — they call initialize() with shell-only backend (no task execution, no token cost). Tier 3 tests (TestCloudRegistry) require OPENSPACE_API_KEY.

Hooks

Add new hooks in .claude/settings.json under "hooks".

Troubleshooting

Memory (MANDATORY)

Update memory files as you go, not at session end. Do not ask — just update.

Maintenance: Run /compact-memory monthly (or when memory-sessions.md exceeds ~200 lines) to compress old entries, prune obsolete decisions, and sync key facts to the knowledge graph.

Full rules: memory-guidelines.md

Agent skills

Issue tracker

Issues live in GitHub Issues (mdmorar/Claude_Code_Boilerplate_Framework). External PRs are not a triage surface. See docs/agents/issue-tracker.md.

Triage labels

Default mattpocock/skills label vocabulary — no overrides. See docs/agents/triage-labels.md.

Domain docs

Single-context repo: one CONTEXT.md + docs/adr/ at repo root. See docs/agents/domain.md.