Melt Reference

Melt Reference

Quick Links

• README — Overview and quick start
• Installation — Setup guide
• Customization — Create your own extensions

The Four Core Skills

/melt — Universal Task Execution

Use when: Complex task that benefits from multi-agent planning.

/melt add a logout button to the navbar

Optional Agent Teams planning (First Principles + AGI-Pilled + dynamic experts as needed) → implements → lints → commits → deploys → verifies in browser → cannot stop until done.

/repair — Unified Debugging Router

Use when: Something is broken (auto-detects web vs mobile).

/repair

Detects platform → routes to /appfix (web) or /mobileappfix (mobile) → loops until healthy.

/burndown — Tech Debt Elimination

Use when: Codebase has accumulated slop or architecture issues.

/burndown src/components/

Consolidates /deslop + /qa into autonomous fix loop → 3 detection agents scan for issues → prioritizes by severity → fixes iteratively → re-scans to verify → cannot stop until critical issues fixed.

/heavy — Multi-Perspective Analysis

Use when: Complex question needing broad perspectives.

/heavy Should we use microservices or monolith?

3-5 parallel Opus agents (First Principles + AGI-Pilled always, Critical Reviewer + dynamic agents as needed) → self-educate via codebase + web + vendor docs → tech-stack aware (Next.js, PydanticAI, Azure) → structured disagreements → adversarial dialogue → intelligence-first, never cost-first → bounded extension (max 3 rounds).

All Slash Commands (19 commands + 5 core skills)

All Skills (26 total)

Registered Hooks (14 scripts)

Auto-Update System (v2)

Smart auto-update with customization preservation. The hook detects local modifications, classifies overlap with upstream changes, and chooses the right update strategy automatically.

Update Flow

Session Start
  ├─ Rate-limited check (5 min)
  ├─ git ls-remote vs local HEAD
  │
  ├─ Up to date → silent exit
  ├─ Behind, clean tree → git pull --ff-only
  ├─ Behind, dirty (no overlap) → stash + pull + pop
  └─ Behind, dirty (overlap) → backup branch + agent instructions

Three Update Paths

Deferred Agent Pattern

When local modifications overlap with upstream changes, the hook outputs structured YAML instructions that the Claude agent executes as its first action. The hook is the sensor (fast, <2s); the agent is the brain (semantic understanding).

The agent classifies each user modification:

• TEMPLATE_FILL: User replaced [YOUR_*] placeholders → preserve values
• PROJECT_GUARD: User added project-specific conditionals → re-add to new version
• FEATURE_ADD: User added new capability → check if upstream added equivalent
• BUG_FIX: User patched a bug → check if upstream fixed it
• CONFIG_OVERRIDE: User changed defaults → preserve overrides

File Classification

The hook categorizes each dirty file:

Bootstrap Safety

Before pulling, the hook verifies the upstream auto-update.py compiles (py_compile). This prevents a broken upstream hook from bricking the update mechanism.

Settings Local Override (v2)

config/settings.local.json provides user overrides that are deep-merged onto config/settings.json:

{
  "env": { "MY_CUSTOM_VAR": "value" },
  "permissions": { "defaultMode": "acceptEdits" },
  "hooks": {
    "PostToolUse": [{ "matcher": "Bash", "hooks": [{"type": "command", "command": "python3 my-hook.py"}] }]
  }
}

Merge rules: Objects deep-merge (nested keys preserved). Arrays replace entirely. Keys starting with _ are stripped. The merged result is written as a real file to ~/.claude/settings.json (replacing the symlink).

Both install.sh and the auto-update hook perform this merge automatically.

User Overlay Directory (v3)

config/user/ provides a gitignored home for user-created extensions:

config/user/           # gitignored from upstream
├── hooks/             # Custom hook scripts
├── skills/            # Custom skill directories
├── commands/          # Custom command files
└── README.md          # Usage guide

When user overlay files exist, install.sh converts directory symlinks to per-file symlinks, linking both upstream and user content into ~/.claude/. This means custom hooks/skills appear alongside upstream ones seamlessly.

Configuration

Memory System (v5 + Native Integration)

Complementary dual-layer memory: Claude Code's native MEMORY.md for project orientation + custom compound memory for task-specific retrieval. Events stored in ~/.claude/memory/{project-hash}/events/.

Native + Custom Integration

The context loader auto-detects native MEMORY.md and adjusts its budget:

A dedup guard prevents injecting compound events whose content (>60% word overlap) is already documented in MEMORY.md. High-utility events can be promoted from compound memory to MEMORY.md via config/scripts/promote-to-memory-md.py.

How It Works

1. Auto-capture (primary path): stop-validator hook archives checkpoint as LESSON-first memory event on every successful stop. Checkpoint requires key_insight (>50 chars), search_terms (2-7 concept keywords), category (any string), optional problem_type (controlled vocabulary), optional core_assertions (max 5 topic/assertion pairs). A secondary stop-quality-agent hook (agent-type) reads the transcript to verify checkpoint honesty for autonomous sessions.
2. Manual capture (deep captures): /compound skill for detailed LESSON/PROBLEM/CAUSE/FIX documentation
3. Auto-injection: compound-context-loader hook injects top 5 relevant events as structured XML at SessionStart (budget-aware: 4.5K with native memory, 8K standalone)
4. Core assertions: Persistent <core-assertions> block injected before <memories> — topic-based dedup (last-write-wins), LRU eviction at 20 entries, compaction at SessionStart
5. 2-signal scoring: Entity overlap (50%) + recency (50%) with entity gate (zero-overlap events rejected outright)
6. MEMORY.md dedup: Events with >60% significant-word overlap against native MEMORY.md are skipped
7. Two-layer crash safety:
   • precompact-capture (PreCompact): injects session summary into post-compaction context
   • stop-validator (Stop): structured LESSON + core assertions capture on clean exit
8. Entity matching: Multi-tier scoring — exact basename (1.0), stem (0.6), concept keyword (0.5), substring (0.35), directory (0.3) — uses max() not average()
9. Gradual freshness curve: Linear ramp 1.0→0.5 over 48h, then exponential decay anchored at 0.5 (half-life 7d), continuous at boundary
10. Problem-type encoding: Controlled vocabulary (race-condition, config-mismatch, api-change, import-resolution, state-management, crash-safety, data-integrity, performance, tooling, dependency-management) — auto-injected as concept entity
11. Mid-session recall: memory-recall hook on Read/Grep/Glob triggers, 8 recalls/session, 30s cooldown, file-locked injection log
12. Dedup: Prefix-hash guard (8-event lookback, 60-min window) prevents duplicates
13. Bootstrap filter: Commit-message-level events automatically excluded from injection
14. Promotion: promote-to-memory-md.py identifies events with citation rate >= 30% and promotes their LESSON content to native MEMORY.md

Storage

• Location: ~/.claude/memory/{project-hash}/events/evt_{timestamp}.json
• Isolation: Project-scoped via SHA256(git_remote_url | repo_root)
• Retention: 90-day TTL, 500 event cap per project
• Format: JSON events with atomic writes (F_FULLFSYNC + os.replace for crash safety)
• Budget: 5 events, 4500-8000 chars (dynamic), score-tiered (600/350/200 chars per event)
• Promotion sidecar: ~/.claude/memory/{project-hash}/promoted-events.json tracks promoted event IDs

Event Schema

{
  "id": "evt_20260131T143022-12345-a1b2c3",
  "ts": "2026-01-31T14:30:22Z",
  "v": 1,
  "type": "compound",
  "content": "LESSON: <key insight>\nDONE: <what was done>",
  "entities": ["crash-safety", "atomic-write", "macOS", "_memory.py", "hooks/_memory.py"],
  "source": "compound",
  "category": "gotcha",
  "problem_type": "crash-safety",
  "meta": {"quality": "rich", "files_changed": ["config/hooks/_memory.py"]}
}

Manual Search

grep -riwl "keyword" ~/.claude/memory/*/events/

ToolSearch (MCP Lazy Loading)

ToolSearch (ENABLE_TOOL_SEARCH=auto in settings.json) defers MCP tool loading until needed, saving 85-95% of context tokens from tool definitions.

Key Facts

• Enabled by default via auto mode — tools are eagerly loaded as fallback if ToolSearch fails
• Chrome MCP is NOT affected — mcp__claude-in-chrome__* tools are injected by the Chrome extension via system prompt, not through user-configured MCP servers
• Affected servers: Maestro MCP and Exa MCP are user-configured and subject to lazy loading
• Discovery pattern: Skills use ToolSearch(query: "server-name") for pre-flight capability detection

Pre-Flight Pattern

Skills with hard MCP dependencies use ToolSearch as a fail-fast check:

# In skill SKILL.md:
ToolSearch(query: "maestro")   # Discovers + loads Maestro MCP tools
ToolSearch(query: "exa")       # Discovers + loads Exa MCP tools

If the MCP server isn't configured, ToolSearch returns no results and the skill can error clearly instead of failing mysteriously mid-execution.

Which Skills Use ToolSearch

Skills without MCP dependencies (/compound, /burndown, /qa, /deslop) need no ToolSearch calls.

Hooks Integration

• exa-search-enforcer: Reminds agents to use ToolSearch(query: "exa") if Exa tools aren't loaded
• stop-validator: Error messages reference ToolSearch discovery for Maestro tools

QMD (Documentation Search)

QMD (tobi/qmd) is a local markdown search engine that provides semantic search over project documentation. When configured, it's preferred over manual docs/index.md reading.

Setup

# Install QMD globally
bun install -g github:tobi/qmd

# Create collection for your project
qmd collection add ~/your-project --name myproject

# Add context descriptions
qmd context add qmd://myproject "Project description for search context"

# Add MCP server to .mcp.json
{
  "mcpServers": {
    "qmd": {
      "command": "/path/to/.bun/bin/qmd",
      "args": ["mcp"]
    }
  }
}

Usage

# Search for relevant docs (preferred)
qmd_search "authentication flow"

# Get specific document
qmd_get "qmd://collection/path/to/doc.md"

# Check index status
qmd_status

Integration with Skills

Fallback Behavior

All QMD integrations include fallback to manual doc reading when QMD is unavailable:

• If qmd_status fails → read docs/index.md manually
• Skills detect QMD via .mcp.json configuration

Deep Dives

Research & Historical

Directory Structure

claude-code-toolkit/   # THIS IS THE SOURCE OF TRUTH
├── config/
│   ├── CLAUDE.md              # User preferences (symlinked to ~/.claude/CLAUDE.md)
│   ├── settings.json          # Hook definitions + Agent Teams + ToolSearch (upstream-owned)
│   ├── settings.local.json    # User overrides, deep-merged onto settings.json (gitignored)
│   ├── settings.local.json.example  # Template for user overrides
│   ├── commands/              # 15 command files
│   ├── hooks/                 # Python/bash hooks (14 registered)
│   ├── rules/                 # Toolkit instruction rules (auto-loaded by Claude Code)
│   │   ├── toolkit-skills.md  # Skill routing, parallelization, fluidity
│   │   ├── toolkit-git.md     # Autonomous git operations
│   │   └── toolkit-search.md  # Exa/QMD search preferences
│   ├── scripts/               # Standalone utilities (promote-to-memory-md.py)
│   ├── skills/                # 26 skills ← EDIT HERE
│   └── user/                  # User overlay directory (gitignored)
│       ├── hooks/             # Custom hook scripts
│       ├── skills/            # Custom skill directories
│       ├── commands/          # Custom command files
│       └── rules/             # Custom rule files
├── docs/                      # Documentation
├── scripts/                   # install.sh, doctor.sh, skill-tester.sh, test-e2e-*.sh
└── README.md

~/.claude/                     # SYMLINKED TO REPO + MEMORY
├── CLAUDE.md → config/CLAUDE.md  # User preferences (thin file)
├── rules → config/rules       # Toolkit instructions (auto-loaded by Claude Code)
├── skills → config/skills     # Symlink (or per-skill symlinks if user overlay exists)
├── hooks → config/hooks       # Symlink (or per-file symlinks if user overlay exists)
├── settings.json              # Symlink to config/settings.json OR merged real file
├── projects/                  # Native Claude Code project data
│   └── {encoded-path}/
│       └── memory/
│           └── MEMORY.md      # Native project memory (auto-detected by hooks)
└── memory/                    # Compound event store (NOT in repo)
    └── {project-hash}/
        ├── events/            # Memory events (JSON)
        ├── core-assertions.jsonl  # Persistent assertions (JSONL)
        ├── manifest.json      # Fast lookup index + utility tracking
        └── promoted-events.json   # Tracks events promoted to MEMORY.md

IMPORTANT: ~/.claude/skills/ is a symlink to config/skills/ in this repo. When you edit skill files, you're editing the repo. Commit changes to preserve them. For user-created extensions, use config/user/ instead — it's gitignored from upstream.