Continuous Claude

Session continuity, token-efficient MCP execution, and agentic workflows for Claude Code.

Table of Contents

• Architecture Overview
• The Problem / The Solution
• Quick Start (project or global install)
• How to Talk to Claude
• Skills vs Agents
• MCP Code Execution
• Continuity System
• Hooks System
• Reasoning History
• Braintrust Session Tracing + Compound Learnings
• Artifact Index (handoff search, outcome tracking)
• TDD Workflow
• Code Quality (qlty)
• Directory Structure
• Environment Variables
• Glossary
• Troubleshooting
• Acknowledgments

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                            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)                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Data Flow: Session Lifecycle

┌─────────────────────────────────────────────────────────────────────────────┐
│                         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     │
           │                           │                    │