GitHub - parcadei/Continuous-Claude-v2: Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context pollution. Agent orchestration with isolated context windows.

┌─────────────────────────────────────────────────────────────────────────────┐
│                            CLAUDE CODE SESSION                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌────────────┐  │
│   │ SessionStart│───▶│   Working   │───▶│  PreCompact │───▶│ SessionEnd │  │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └─────┬──────┘  │
│          │                  │                  │                  │         │
│          ▼                  ▼                  ▼                  ▼         │
│   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌───────────┐   │
│   │Load Ledger   │   │PreToolUse    │   │Auto-Handoff  │   │Mark       │   │
│   │Load Handoff  │   │ TS Preflight │   │Block Manual  │   │Outcome    │   │
│   │Surface       │   │PostToolUse   │   │              │   │Cleanup    │   │
│   │Learnings     │   │UserPrompt    │   │              │   │Learn      │   │
│   └──────────────┘   └──────────────┘   └──────────────┘   └───────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                │                │                │                │
                ▼                ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              DATA LAYER                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  thoughts/                    .claude/cache/                                │
│  ├── ledgers/                 ├── artifact-index/                           │
│  │   └── CONTINUITY_*.md          └── context.db (SQLite+FTS5)             │
│  └── shared/                  ├── learnings/                                │
│      ├── handoffs/                └── <date>_<session>.md                   │
│      │   └── <session>/       └── braintrust_sessions/                      │
│      │       └── *.md             └── <session>.json                        │
│      └── plans/                                                             │
│          └── *.md             .git/claude/                                  │
│                               └── commits/                                  │
│                                   └── <hash>/reasoning.md                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                │                                        │
                ▼                                        ▼
┌───────────────────────────────────┐  ┌───────────────────────────────────┐
│          SKILLS                   │  │           AGENTS                   │
├───────────────────────────────────┤  ├───────────────────────────────────┤
│                                   │  │                                   │
│  ┌──────────────────┐             │  │  ┌──────────────────┐             │
│  │ continuity_ledger│ Save state  │  │  │ plan-agent       │ Create plan │
│  ├──────────────────┤             │  │  ├──────────────────┤             │
│  │ create_handoff   │ End session │  │  │ validate-agent   │ Check tech  │
│  ├──────────────────┤             │  │  ├──────────────────┤             │
│  │ resume_handoff   │ Resume work │  │  │ implement_plan   │ Execute     │
│  ├──────────────────┤             │  │  ├──────────────────┤             │
│  │ commit           │ Git commit  │  │  │ research-agent   │ Research    │
│  ├──────────────────┤             │  │  ├──────────────────┤             │
│  │ tdd-workflow     │ Red/Green   │  │  │ debug-agent      │ Debug       │
│  ├──────────────────┤             │  │  ├──────────────────┤             │
│  │ hook-developer   │ Hook ref    │  │  │ rp-explorer      │ Codebase    │
│  ├──────────────────┤             │  │  └──────────────────┘             │
│  │ compound-learn   │ Make rules  │  │                                   │
│  └──────────────────┘             │  │                                   │
└───────────────────────────────────┘  └───────────────────────────────────┘
                │                                        │
                └────────────────────┬───────────────────┘
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           SCRIPTS (MCP Execution)                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Artifact Index              Braintrust              MCP Tools              │
│  ┌──────────────────┐        ┌──────────────────┐    ┌──────────────────┐   │
│  │ artifact_index   │        │ braintrust_       │    │ perplexity_      │   │
│  │ artifact_query   │        │    analyze        │    │    search        │   │
│  │ artifact_mark    │        │ (--learn,         │    │ nia_docs         │   │
│  └──────────────────┘        │  --sessions)      │    │ firecrawl_scrape │   │
│                              └──────────────────┘    │ github_search    │   │
│                                                      │ morph_search     │   │
│                                                      │ ast_grep_find    │   │
│                                                      │ qlty_check       │   │
│                                                      └──────────────────┘   │
│                                                                             │
│  Executed via: uv run python -m runtime.harness scripts/<script>.py        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        EXTERNAL SERVICES (Optional)                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │Braintrust│  │Perplexity│  │ Firecrawl│  │   Morph  │  │   Nia    │      │
│  │ Tracing  │  │  Search  │  │  Scrape  │  │ WarpGrep │  │   Docs   │      │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │
│                                                                             │
│  Local-only: git, ast-grep, qlty                                           │
│  License required: repoprompt (Pro for MCP tools)                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                         THE CONTINUITY LOOP                                 │
└─────────────────────────────────────────────────────────────────────────────┘

  1. SESSION START                     2. WORKING
  ┌────────────────────┐               ┌────────────────────┐
  │                    │               │                    │
  │  Ledger loaded ────┼──▶ Context    │  PostToolUse ──────┼──▶ Index handoffs
  │  Handoff loaded    │               │  UserPrompt ───────┼──▶ Skill hints
  │  Learnings shown   │               │  SubagentStop ─────┼──▶ Agent reports
  │                    │               │                    │
  └────────────────────┘               └────────────────────┘
           │                                    │
           │                                    ▼
           │                           ┌────────────────────┐
           │                           │ 3. PRE-COMPACT     │
           │                           │                    │
           │                           │  Auto-handoff ─────┼──▶ thoughts/
           │                           │  Block manual      │
           │                           │                    │
           │                           └────────────────────┘
           │                                    │
           │                                    ▼
           │                           ┌────────────────────┐
           │                           │ 4. SESSION END     │
           │                           │                    │
           │                           │  Mark outcome ─────┼──▶ artifact.db
           │                           │  Extract learnings ┼──▶ cache/
           │                           │  Cleanup           │
           │                           │                    │
           │                           └────────────────────┘
           │                                    │
           │                                    │
           └──────────────◀────── /clear ◀──────┘
                          Fresh context + state preserved

┌─────────────────────────────────────────────────────────────────────────────┐
│                    PLAN → VALIDATE → IMPLEMENT                              │
└─────────────────────────────────────────────────────────────────────────────┘

  "Design a feature"          "Ready to implement"        "Execute the plan"
         │                           │                           │
         ▼                           ▼                           ▼
  ┌──────────────┐           ┌──────────────┐           ┌──────────────┐
  │ plan-agent   │──────────▶│validate-agent│──────────▶│implement_plan│
  │              │           │              │           │              │
  │ Research     │           │ RAG-judge    │           │ Orchestrate  │
  │ Design       │           │ WebSearch    │           │ Task agents  │
  │ Write plan   │           │ Flag issues  │           │ TDD workflow │
  └──────────────┘           └──────────────┘           └──────────────┘
         │                           │                           │
         ▼                           ▼                           ▼
  thoughts/shared/           Validation report         thoughts/shared/
  plans/*.md                 (in context)              handoffs/session/*.md

Session Start: Full context, high signal
    ↓ work, work, work
Compaction 1: Some detail lost
    ↓ work, work, work
Compaction 2: Context getting murky
    ↓ work, work, work
Compaction 3: Now working with compressed noise
    ↓ Claude starts hallucinating context

Session Start: Fresh context + ledger loaded
    ↓ focused work
Complete task, save to ledger
    ↓ /clear
Fresh context + ledger loaded
    ↓ continue with full signal

# Clone
git clone https://github.com/parcadei/claude-continuity-kit.git
cd claude-continuity-kit

# Install Python deps
uv sync

# Configure (optional - add API keys for extra features)
cp .env.example .env

# Start
claude

# After cloning and syncing
./install-global.sh

┌─────────────────────────────────────────────────────────────┐
│  Continuous Claude - Global Installation                    │
└─────────────────────────────────────────────────────────────┘

This will install to: ~/.claude

⚠️  WARNING: The following will be REPLACED:
   • ~/.claude/skills/     (all skills)
   • ~/.claude/agents/     (all agents)
   • ~/.claude/rules/      (all rules)
   • ~/.claude/hooks/      (all hooks)
   • ~/.claude/settings.json (backup created)

✓ PRESERVED (not touched):
   • ~/.claude/.env
   • ~/.claude/cache/
   • ~/.claude/state/

📦 A full backup will be created at ~/.claude-backup-<timestamp>

Continue with installation? [y/N] y

Installing Continuous Claude to ~/.claude...

✓ uv installed (Python package manager)
✓ qlty installed (code quality toolkit)
Installing MCP runtime package globally...
✓ MCP commands installed: mcp-exec, mcp-generate, mcp-discover

Creating full backup at ~/.claude-backup-20251225_043445...
Backup complete. To restore: rm -rf ~/.claude && mv ~/.claude-backup-<timestamp> ~/.claude

Copying skills...
Copying agents...
Copying rules...
Copying hooks...
Copying scripts...
Copying plugins...
Installing settings.json...
Creating .env template...

Installation complete!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  GLOBAL MCP SERVERS DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 9 global MCP servers in ~/.claude.json:
  • agi-memory
  • ast-grep
  • beads
  • firecrawl
  • github
  ...

These servers are inherited by ALL projects and can cause
skills to use unexpected tools (e.g., /onboard using 'beads').

Recommended: Remove global MCP servers and configure them
per-project in each project's .mcp.json instead.

Remove global MCP servers from ~/.claude.json? [y/N] y
Backup created: ~/.claude.json.backup.<timestamp>
✓ Removed global MCP servers

To restore: cp ~/.claude.json.backup.<timestamp> ~/.claude.json

cd your-project
~/.claude/scripts/init-project.sh

┌─────────────────────────────────────────────────────────────┐
│  Continuous Claude - Project Initialization                 │
└─────────────────────────────────────────────────────────────┘

This will create:
  • thoughts/ledgers/     - Continuity ledgers
  • thoughts/shared/      - Plans and handoffs
  • .claude/cache/        - Artifact Index database

Project: /path/to/your-project

Continue? [y/N] y

Creating directories...
✓ thoughts/ledgers/
✓ thoughts/shared/handoffs/
✓ thoughts/shared/plans/
✓ .claude/cache/artifact-index/

Initializing Artifact Index database...
✓ Created context.db with FTS5 schema

Adding to .gitignore...
✓ Added .claude/cache/ to .gitignore

Project initialized! You can now:
  • Use /continuity_ledger to save session state
  • Use /create_handoff to create session handoffs
  • Use /onboard to analyze the codebase

# 1. Initialize project structure
~/.claude/scripts/init-project.sh

# 2. Start Claude and onboard
claude
> /onboard

1. plan-agent     → Creates plan in thoughts/shared/plans/
2. validate-agent → RAG-judge (past precedent) + WebSearch (best practices)
3. implement_plan → Executes with task agents, creates handoffs

implement_plan (orchestrator)
    ├── task-agent (task 1) → handoff-01.md
    ├── task-agent (task 2) → handoff-02.md
    └── task-agent (task 3) → handoff-03.md

# Example: run a script
uv run python -m runtime.harness scripts/qlty_check.py --fix

# Available scripts
ls scripts/

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}

# Global commands available everywhere
mcp-exec scripts/my_script.py      # Run a script
mcp-generate                        # Generate wrappers for configured servers

# scripts/my_tool.py
"""
USAGE: uv run python -m runtime.harness scripts/my_tool.py --query "search term"
"""
import argparse
from runtime.mcp_client import call_mcp_tool

async def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--query", required=True)
    args = parser.parse_args()

    # Tool format: serverName__toolName
    result = await call_mcp_tool("my-server__search", {"query": args.query})
    print(result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

mkdir -p .claude/skills/my-tool
cat > .claude/skills/my-tool/SKILL.md << 'EOF'
---
name: my-tool
description: Search with my tool
---
# My Tool

```bash
uv run python -m runtime.harness scripts/my_tool.py --query "your query"

**Adding skill triggers for auto-activation:**

```json
// .claude/skills/skill-rules.json
{
  "skills": {
    "my-tool": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "description": "Search with my tool",
      "promptTriggers": {
        "keywords": ["my-tool", "search with tool"],
        "intentPatterns": ["(search|find).*?with.*?tool"]
      }
    }
  }
}

## Step 3: Research with MCP Tools

### For External Knowledge
```bash
# Documentation search (Nia)
uv run python -m runtime.harness scripts/nia_docs.py --query "your query"

# Web research (Perplexity)
uv run python -m runtime.harness scripts/perplexity_search.py --query "your query"

# Fast code search (Morph)
uv run python -m runtime.harness scripts/morph_search.py --query "pattern" --path "."

Agents use MCP scripts to:
- Perform research across multiple sources
- Investigate issues with codebase search
- Apply fixes using fast editing tools
- Gather information for analysis

See `.claude/agents/research-agent.md` and `.claude/agents/debug-agent.md` for complete examples.

#### Full Pattern: MCP Server → Scripts → Skills → Agents

The complete integration flow:

**Real-world example:** `morph-search`

1. **Server:** `morph` MCP server in `mcp_config.json`
2. **Script:** `scripts/morph_search.py` with `--query`, `--path` args
3. **Skill:** `.claude/skills/morph-search/SKILL.md` documents usage
4. **Triggers:** `.claude/skills/skill-rules.json` activates on "search code", "fast search"
5. **Agents:** `research-agent.md` and `debug-agent.md` use for codebase search
6. **Activation:** User says "search code for error handling" → auto-suggests

**Key benefits:**
- **Progressive disclosure:** 110 tokens (99.6% reduction) vs full tool schemas
- **Reusability:** Scripts work for agents, skills, and direct execution
- **Auto-discovery:** skill-rules.json enables context-aware suggestions
- **Flexibility:** Change parameters via CLI, no code edits needed

---

## Continuity System

### Ledger (within session)

Before running `/clear`:

Creates/updates `CONTINUITY_CLAUDE-<session>.md` with:
- Goal and constraints
- What's done, what's next
- Key decisions
- Working files

After `/clear`, the ledger loads automatically.

### Handoff (between sessions)

When done for the day:

Creates `thoughts/handoffs/<session>/handoff-<timestamp>.md` with:
- Detailed context
- Recent changes with file:line references
- Learnings and patterns
- Next steps

Next session:

---

## Hooks System

Hooks are the backbone of continuity. They intercept Claude Code lifecycle events and automate state preservation.

### StatusLine (Context Indicator)

The colored status bar shows context usage in real-time:

**Color coding:**

| Color | Range | Meaning |
|-------|-------|---------|
| 🟢 Green | < 60% | Normal - full continuity info shown |
| 🟡 Yellow | 60-79% | Warning - consider creating handoff soon |
| 🔴 Red | ≥ 80% | Critical - shows `⚠` icon, prompts handoff |

The StatusLine writes context % to `/tmp/claude-context-pct-{SESSION_ID}.txt` (per-session to avoid multi-instance conflicts).

### Hook Events

| Event | When | What This Kit Does |
|-------|------|-------------------|
| **SessionStart** | New session, `/clear`, compact | Loads ledger + latest handoff into context |
| **PreToolUse** | Before tool execution | **TypeScript preflight** - catches type errors before Edit/Write on .ts files |
| **PreCompact** | Before context compaction | Creates auto-handoff, blocks manual compact |
| **UserPromptSubmit** | Before processing user message | Shows skill suggestions, context warnings |
| **PostToolUse** | After Edit/Write/Bash | Tracks modified files for auto-summary |
| **SubagentStop** | Agent finishes | Logs agent completion |
| **SessionEnd** | Session closes | Cleanup temp files |

### SessionStart Hook

Runs on: `resume`, `clear`, `compact`

**What it does:**
1. Finds most recent `CONTINUITY_CLAUDE-*.md` ledger
2. Extracts Goal and current focus ("Now:")
3. Finds latest handoff (task-*.md or auto-handoff-*.md)
4. Injects ledger + handoff into system context

**Result:** After `/clear`, Claude immediately knows:
- What you're working on
- What's done vs pending
- Recent decisions and learnings

### PreCompact Hook

Runs: Before any compaction

**Auto-compact (trigger: auto):**
1. Parses transcript to extract tool calls and responses
2. Generates detailed `auto-handoff-<timestamp>.md` with:
   - Files modified
   - Recent tool outputs
   - Current work state
3. Saves to `thoughts/handoffs/<session>/`

**Manual compact (trigger: manual):**
- Blocks compaction
- Prompts you to run `/continuity_ledger` first

### UserPromptSubmit Hook

Runs: Every message you send

**Two functions:**

1. **Skill activation** - Scans your message for keywords defined in `skill-rules.json`. Shows relevant skills:

2. **Context warnings** - Reads context % and shows tiered warnings:
- 70%: `Consider handoff when you reach a stopping point.`
- 80%: `Recommend: /create_handoff then /clear soon`
- 90%: `CONTEXT CRITICAL: Run /create_handoff NOW!`

### TypeScript Preflight Hook (PreToolUse)

Runs: Before Edit/Write on `.ts` or `.tsx` files

**What it does:**
1. Runs `tsc --noEmit` on the file being edited
2. If type errors exist, blocks the edit and shows errors to Claude
3. Claude fixes the issues before proceeding

**Why this matters:** Catches type errors early, before they compound across multiple edits. Claude sees the errors in context and can fix them immediately.

**Example output when blocked:**

### How Hooks Work

Hooks are **pre-bundled** - no runtime dependencies needed. Shell wrappers call bundled JS:

```bash
# .claude/hooks/session-start-continuity.sh
#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | node dist/session-start-continuity.mjs

cd .claude/hooks
vim src/session-start-continuity.ts  # Edit source
./build.sh                            # Rebuild dist/

// Input varies by event type
interface SessionStartInput {
  source: 'startup' | 'resume' | 'clear' | 'compact';
  session_id: string;
}

// Output controls behavior (varies by hook type)
interface HookOutput {
  continue?: boolean;             // true to proceed (default)
  decision?: 'block';             // Block stops the action (PreToolUse only)
  reason?: string;                // Shown when blocking
  hookSpecificOutput?: {          // Injected into context
    additionalContext: string;
  };
}

{
  "statusLine": {
    "type": "command",
    "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/status.sh"
  },
  "hooks": {
    "SessionStart": [{
      "matcher": "clear",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-continuity.sh"
      }]
    }]
  }
}

"recall what was tried for authentication bugs"
→ Searches .git/claude/commits/*/reasoning.md
→ Returns: "In commit abc123, tried X but failed because Y, fixed with Z"

┌─────────────────────────────────────────────────────────────────────────────┐
│                        BRAINTRUST TRACING ARCHITECTURE                      │
└─────────────────────────────────────────────────────────────────────────────┘

                             ┌─────────────────┐
                             │   Braintrust    │
                             │     Cloud       │
                             │  (braintrust.   │
                             │      dev)       │
                             └────────┬────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
              ▼                       ▼                       ▼
      ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
      │   Project A  │       │   Project B  │       │   Project C  │
      │   (traces)   │       │   (traces)   │       │   (traces)   │
      └──────────────┘       └──────────────┘       └──────────────┘


                    WITHIN A PROJECT: Session Trace Structure
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   SESSION (root span) ─── created by SessionStart hook                      │
│   │                                                                         │
│   ├── TURN 1 (task span) ─── created by UserPromptSubmit hook              │
│   │   │                                                                     │
│   │   ├── LLM Call (llm span) ─── created by Stop hook                     │
│   │   │   └── input: [user message], output: [assistant + tool_use]        │
│   │   │                                                                     │
│   │   ├── Tool: Read file.ts (tool span) ─── PostToolUse hook              │
│   │   ├── Tool: Edit file.ts (tool span) ─── PostToolUse hook              │
│   │   │                                                                     │
│   │   └── LLM Call (llm span) ─── created by Stop hook                     │
│   │       └── input: [tool results], output: [assistant response]          │
│   │                                                                         │
│   ├── TURN 2 (task span)                                                   │
│   │   └── ... (same structure)                                             │
│   │                                                                         │
│   └── TURN N (task span)                                                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


                    CROSS-SESSION: The Learning Loop
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   SESSION 1                SESSION 2                SESSION 3               │
│   ┌─────────┐              ┌─────────┐              ┌─────────┐             │
│   │  Work   │              │  Work   │              │  Work   │             │
│   │   +     │              │   +     │              │   +     │             │
│   │ Traces  │              │ Traces  │              │ Traces  │             │
│   └────┬────┘              └────┬────┘              └────┬────┘             │
│        │                        │                        │                  │
│        ▼                        ▼                        ▼                  │
│   ┌─────────┐              ┌─────────┐              ┌─────────┐             │
│   │SessionEnd              │SessionEnd              │SessionEnd             │
│   │--learn  │              │--learn  │              │--learn  │             │
│   └────┬────┘              └────┬────┘              └────┬────┘             │
│        │                        │                        │                  │
│        ▼                        ▼                        ▼                  │
│   ┌─────────────────────────────────────────────────────────────┐           │
│   │                .claude/cache/learnings/                      │           │
│   │  ├── 2025-12-24_session-1.md  (What Worked, What Failed)    │           │
│   │  ├── 2025-12-24_session-2.md  (Key Decisions, Patterns)     │           │
│   │  └── 2025-12-25_session-3.md                                │           │
│   └──────────────────────────┬──────────────────────────────────┘           │
│                              │                                              │
│                              ▼                                              │
│                     ┌─────────────────┐                                     │
│                     │  SessionStart   │                                     │
│                     │  (next session) │                                     │
│                     │                 │                                     │
│                     │ Surfaces recent │                                     │
│                     │ learnings (48h) │                                     │
│                     └─────────────────┘                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘


                    HANDOFF ↔ TRACE CORRELATION
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   Handoff File (thoughts/shared/handoffs/session/task-01.md)               │
│   ┌─────────────────────────────────────────────────────────────┐           │
│   │ ---                                                         │           │
│   │ root_span_id: abc-123-main  ◄──── Links to Braintrust trace│           │
│   │ turn_span_id: def-456-turn  ◄──── Span that created it     │           │
│   │ session_id: abc-123-main                                    │           │
│   │ ---                                                         │           │
│   │ # Task: Implement feature X                                 │           │
│   │ ...                                                         │           │
│   └─────────────────────────────────────────────────────────────┘           │
│                              │                                              │
│                              │ Query by span_id                             │
│                              ▼                                              │
│   ┌─────────────────────────────────────────────────────────────┐           │
│   │                    Braintrust Trace                         │           │
│   │  - See exact tool calls that produced the handoff           │           │
│   │  - Review token usage and timing                            │           │
│   │  - Debug what went wrong in failed sessions                 │           │
│   └─────────────────────────────────────────────────────────────┘           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

1. You work → Braintrust traces every interaction
2. /clear or exit → SessionEnd triggers braintrust_analyze.py --learn
3. LLM extracts: What Worked, What Failed, Key Decisions, Patterns
4. Saves to: .claude/cache/learnings/<date>_<session_id>.md
5. Next session → SessionStart surfaces learnings from last 48h

# Handoff frontmatter (auto-injected by PostToolUse hook)
root_span_id: abc-123-main    # Braintrust trace ID
turn_span_id: def-456-turn    # Span that created this handoff
session_id: abc-123-main      # Claude session ID

{
  "hooks": {
    "SessionStart": [
      // Comment out the braintrust-tracing hooks
    ]
  }
}

"compound my learnings"
→ Analyzes .claude/cache/learnings/*.md
→ Identifies recurring patterns
→ Creates new rules in .claude/rules/
→ Archives processed learnings

1. Create handoff → PostToolUse hook indexes it immediately
2. Session ends → Prompts you to mark outcome
3. Next session → SessionStart surfaces unmarked handoffs
4. Mark outcomes → Improves future session recommendations

# List unmarked handoffs
uv run python scripts/artifact_query.py --unmarked

# Mark an outcome
uv run python scripts/artifact_mark.py \
  --handoff abc123 \
  --outcome SUCCEEDED

# Search handoffs by content
uv run python scripts/artifact_query.py --search "authentication bug"

# Get session history
uv run python scripts/artifact_query.py --session open-source-release

1. RED    - Write failing test first
2. GREEN  - Minimal code to pass
3. REFACTOR - Clean up, tests stay green

curl -fsSL https://qlty.sh/install.sh | bash

"lint my code"
"check code quality"
"auto-fix issues"

qlty check --fix
qlty fmt
qlty metrics

.claude/
├── skills/          # Skill definitions (SKILL.md)
├── hooks/           # Session lifecycle (TypeScript)
├── agents/          # Agent configurations
├── rules/           # Behavioral rules
└── settings.json    # Hook registrations

scripts/             # MCP workflow scripts
servers/             # Generated tool wrappers (gitignored)
thoughts/            # Research, plans, handoffs (gitignored)
src/runtime/         # MCP execution runtime

# Required for paid services
GITHUB_PERSONAL_ACCESS_TOKEN="ghp_..."
PERPLEXITY_API_KEY="pplx-..."
FIRECRAWL_API_KEY="fc-..."
MORPH_API_KEY="sk-..."
NIA_API_KEY="nk_..."