Continuous-Claude-v2

# Continuous Claude > A persistent, learning, multi-agent development environment built on Claude Code [](LICENSE) [](https://claude.ai/code) [](#skills-system) [](#agents-system) [](#hooks-system) **Continuous Claude** transforms Claude Code into a continuously learning system that maintains context across sessions, orchestrates specialized agents, and eliminates wasting tokens through intelligent code analysis. ## Table of Contents - [Why Continuous Claude?](#why-continuous-claude) - [Design Principles](#design-principles) - [How to Talk to Claude](#how-to-talk-to-claude) - [Quick Start](#quick-start) - [Architecture](#architecture) - [Core Systems](#core-systems) - [Skills (109)](#skills-system) - [Agents (32)](#agents-system) - [Hooks (30)](#hooks-system) - [TLDR Code Analysis](#tldr-code-analysis) - [Memory System](#memory-system) - [Continuity System](#continuity-system) - [Math System](#math-system) - [Workflows](#workflows) - [Installation](#installation) - [Updating](#updating) - [Configuration](#configuration) - [Contributing](#contributing) - [License](#license) --- ## Why Continuous Claude? Claude Code has a **compaction problem**: when context fills up, the system compacts your conversation, losing nuanced understanding and decisions made during the session. **Continuous Claude solves this with:** | Problem | Solution | |---------|----------| | Context loss on compaction | YAML handoffs - more token-efficient transfer | | Starting fresh each session | Memory system recalls + daemon auto-extracts learnings | | Reading entire files burns tokens | 5-layer code analysis + semantic index | | Complex tasks need coordination | Meta-skills orchestrate agent workflows | | Repeating workflows manually | 109 skills with natural language triggers | **The mantra: Compound, don't compact.** Extract learnings automatically, then start fresh with full context. ### Why "Continuous"? Why "Compounding"? The name is a pun. **Continuous** because Claude maintains state across sessions. **Compounding** because each session makes the system smarter—learnings accumulate like compound interest. --- ## Design Principles An agent is five things: **Prompt + Tools + Context + Memory + Model**. | Component | What We Optimize | |-----------|------------------| | **Prompt** | Skills inject relevant context; hooks add system reminders | | **Tools** | TLDR reduces tokens; agents parallelize work | | **Context** | Not just *what* Claude knows, but *how* it's provided | | **Memory** | Daemon extracts learnings; recall surfaces them | | **Model** | Becomes swappable when the other four are solid | ### Anti-Complexity We resist plugin sprawl. Every MCP, subscription, and tool you add promises improvement but risks breaking context, tools, or prompts through clashes. **Our approach:** - **Time, not money** — No required paid services. Perplexity and NIA are optional, high-value-per-token. - **Learn, don't accumulate** — A system that learns handles edge cases better than one that collects plugins. - **Shift-left validation** — Hooks run pyright/ruff after edits, catching errors before tests. The failure modes of complex systems are structurally invisible until they happen. A learning, context-efficient system doesn't prevent all failures—but it recovers and improves. --- ## How to Talk to Claude **You don't need to memorize slash commands.** Just describe what you want naturally. ### The Skill Activation System When you send a message, a hook injects context that tells **Claude** which skills and agents are relevant. Claude infers from a rule-based system and decides which tools to use. ``` > "Fix the login bug in auth.py" 🎯 SKILL ACTIVATION CHECK ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ CRITICAL SKILLS (REQUIRED): → create_handoff 📚 RECOMMENDED SKILLS: → fix → debug 🤖 RECOMMENDED AGENTS (token-efficient): → debug-agent → scout ACTION: Use Skill tool BEFORE responding ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### Priority Levels | Level | Meaning | |-------|---------| | ⚠️ **CRITICAL** | Must use (e.g., handoffs before ending session) | | 📚 **RECOMMENDED** | Should use (e.g., workflow skills) | | 💡 **SUGGESTED** | Consider using (e.g., optimization tools) | | 📌 **OPTIONAL** | Nice to have (e.g., documentation helpers) | ### Natural Language Examples | What You Say | What Activates | |--------------|----------------| | "Fix the broken login" | `/fix` workflow → debug-agent, scout | | "Build a user dashboard" | `/build` workflow → plan-agent, kraken | | "I want to understand this codebase" | `/explore` + scout agent | | "What could go wrong with this plan?" | `/premortem` | | "Help me figure out what I need" | `/discovery-interview` | | "Done for today" | `create_handoff` (critical) | | "Resume where we left off" | `resume_handoff` | | "Research auth patterns" | oracle agent + perplexity | | "Find all usages of this API" | scout agent + ast-grep | ### Why This Approach? | Benefit | How | |---------|-----| | **More Discoverable** | Don't need to know commands exist | | **Context-Aware** | System knows when you're 90% through context | | **Reduces Cognitive Load** | Describe intent naturally, get curated suggestions | | **Power User Friendly** | Still supports /fix, /build, etc. directly | ### Skill vs Workflow vs Agent | Type | Purpose | Example | |------|---------|---------| | **Skill** | Single-purpose tool | `commit`, `tldr-code`, `qlty-check` | | **Workflow** | Multi-step process | `/fix` (sleuth → premortem → kraken → commit) | | **Agent** | Specialized sub-session | scout (exploration), oracle (research) | [See detailed skill activation docs →](docs/skill-activation.md) --- ## Quick Start ### Prerequisites - Python 3.11+ - [uv](https://github.com/astral-sh/uv) package manager - Docker (for PostgreSQL) - Claude Code CLI ### Installation ```bash # Clone git clone https://github.com/parcadei/Continuous-Claude-v3.git cd Continuous-Claude-v3/opc # Run setup wizard (12 steps) uv run python -m scripts.setup.wizard ``` > **Note:** The `pyproject.toml` is in `opc/`. Always run `uv` commands from the `opc/` directory. ### What the Wizard Does | Step | What It Does | |------|--------------| | 1 | Backup existing .claude/ config (if present) | | 2 | Check prerequisites (Docker, Python, uv) | | 3-5 | Database + API key configuration | | 6-7 | Start Docker stack, run migrations | | 8 | Install Claude Code integration (32 agents, 109 skills, 30 hooks) | | 9 | Math features (SymPy, Z3, Pint - optional) | | 10 | TLDR code analysis tool | | 11-12 | Diagnostics tools + Loogle (optional) | #### To Uninstall: ``` cd Continuous-Claude-v3/opc uv run python -m scripts.setup.wizard --uninstall ``` **What it does** 1. Archives your current setup → Moves ~/.claude to ~/.claude-v3.archived.<timestamp> 2. Restores your backup → Finds the most recent ~/.claude.backup.* (created during install) and restores it 3. Preserves user data → Copies these back from the archive: - history.jsonl (your command history) - mcp_config.json (MCP servers) - .env (API keys) - projects.json (project configs) - file-history/ directory - projects/ directory 4. Removes CC-v3 additions → Everything else (hooks, skills, agents, rules) **Safety Features** - Your current setup is archived with timestamp - nothing gets deleted - The wizard asks for confirmation before proceeding - It restores from the backup that was made during installation - All your Claude Code settings stay intact ### Remote Database Setup By default, CC-v3 runs PostgreSQL locally via Docker. For remote database setups: #### 1. Database Preparation ```bash # Connect to your remote PostgreSQL instance psql -h hostname -U user -d continuous_claude # Enable pgvector extension (requires superuser or rds_superuser) CREATE EXTENSION IF NOT EXISTS vector; # Apply the schema (from your local clone) psql -h hostname -U user -d continuous_claude -f docker/init-schema.sql ``` > **Managed PostgreSQL tips:** > - **AWS RDS**: Add `vector` to `shared_preload_libraries` in DB Parameter Group > - **Supabase**: Enable via Database Extensions page > - **Azure Database**: Use Extensions pane to enable pgvector #### 2. Connection Configuration Set `CONTINUOUS_CLAUDE_DB_URL` in `~/.claude/settings.json`: ```json { "env": { "CONTINUOUS_CLAUDE_DB_URL": "postgresql://user:password@hostname:5432/continuous_claude" } } ``` Or export before running Claude: ```bash export CONTINUOUS_CLAUDE_DB_URL="postgresql://user:password@hostname:5432/continuous_claude" claude ``` See `.env.example` for all available environment variables. ### First Session ```bash # Start Claude Code claude # Try a workflow > /workflow ``` ### First Session Commands | Command | What it does | |---------|--------------| | `/workflow` | Goal-based routing (Research/Plan/Build/Fix) | | `/fix bug <description>` | Investigate and fix a bug | | `/build greenfield <feature>` | Build a new feature from scratch | | `/explore` | Understand the codebase | | `/premortem` | Risk analysis before implementation | --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────┐ │ CONTINUOUS CLAUDE │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Skills │ │ Agents │ │ Hooks │ │ │ │ (109) │───▶│ (32) │◀───│ (30) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ TLDR Code Analysis │ │ │ │ L1:AST → L2:CallGraph → L3:CFG → L4:DFG → L5:Slicing │ │ │ │ (95% token savings) │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Memory │ │ Continuity │ │ Coordination│ │ │ │ System │ │ Ledgers │ │ Layer │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Data Flow: Session Lifecycle ``` SessionStart Working SessionEnd │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Load │ │ Track │ │ Save │ │ context │─────────────────▶│ changes │──────────────────▶│ state │ └─────────┘ └─────────┘ └─────────┘ │ │ │ ├── Continuity ledger ├── File claims ├── Handoff ├── Memory recall ├── TLDR indexing ├── Learnings └── Symbol index └── Blackboard └── Outcome │ ▼ ┌─────────┐ │ /clear │ │ Fresh │ │ context │ └─────────┘ ``` ### The Continuity Loop (Detailed) ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ THE CONTINUITY LOOP │ └─────────────────────────────────────────────────────────────────────────────┘ 1. SESSION START 2. WORKING ┌────────────────────┐ ┌────────────────────┐ │ │ │ │ │ Ledger loaded ────┼──▶ Context │ PostToolUse ──────┼──▶ Index handoffs │ Handoff loaded │ │ UserPrompt ───────┼──▶ Skill hints │ Memory recalled │ │ Edit tracking ────┼──▶ Dirty flag++ │ TLDR cache warmed │ │ SubagentStop ─────┼──▶ Agent reports │ │ │ │ └────────────────────┘ └────────────────────┘ │ │ │ ▼ │ ┌────────────────────┐ │ │ 3. PRE-COMPACT │ │ │ │ │ │ Auto-handoff ─────┼──▶ thoughts/shared/ │ │ (YAML format) │ handoffs/*.yaml │ │ Dirty > 20? ──────┼──▶ TLDR re-index │ │ │ │ └────────────────────┘ │ │ │ ▼ │ ┌────────────────────┐ │ │ 4. SESSION END │ │ │ │ │ │ Stale heartbeat ──┼──▶ Daemon wakes │ │ Daemon spawns ────┼──▶ Headless Claude │ │ Thinking blocks ──┼──▶ archival_memory │ │ │ │ └────────────────────┘ │ │ │ │ └──────────────◀────── /clear ◀──────┘ Fresh context + state preserved ``` ### Workflow Chains ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ META-SKILL WORKFLOWS │ └─────────────────────────────────────────────────────────────────────────────┘ /fix bug /build greenfield ───────── ───────────────── ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ sleuth │─▶│ premortem│ │discovery │─▶│plan-agent│ │(diagnose)│ │ (risk) │ │(clarify) │ │ (design) │ └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ kraken │ │ validate │ │ (fix) │ │ (check) │ └────┬─────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ arbiter │ │ kraken │ │ (test) │ │(implement│ └────┬─────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ commit │ │ commit │ └──────────┘ └──────────┘ /tdd /refactor ──── ───────── ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │plan-agent│─▶│ arbiter │ │ phoenix │─▶│ warden │ │ (design) │ │(tests 🔴)│ │(analyze) │ │ (review) │ └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ kraken │ │ kraken │ │(code 🟢) │ │(transform│ └────┬─────┘ └────┬─────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ arbiter │ │ judge │ │(verify ✓)│ │ (review) │ └──────────┘ └──────────┘ ``` ### Data Layer Architecture ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATA LAYER ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ TLDR 5-LAYER CODE ANALYSIS SEMANTIC INDEX │ │ ┌────────────────────────┐ ┌────────────────────────┐ │ │ │ L1: AST (~500 tok) │ │ BGE-large-en-v1.5 │ │ │ │ └── Functions, │ │ ├── All 5 layers │ │ │ │ classes, sigs │ │ ├── 10 lines context │ │ │ │ │ │ └── FAISS index │ │ │ │ L2: Call Graph (+440) │ │ │ │ │ │ └── Cross-file │──────────────│ Query: "auth logic" │ │ │ │ dependencies │ │ Returns: ranked funcs │ │ │ │ │ └────────────────────────┘ │ │ │ L3: CFG (+110 tok) │ │ │ │ └── Control flow │ │ │ │ │ MEMORY (PostgreSQL+pgvector) │ │ │ L4: DFG (+130 tok) │ ┌────────────────────────┐ │ │ │ └── Data flow │ │ sessions (heartbeat) │ │ │ │ │ │ file_claims (locks) │ │ │ │ L5: PDG (+150 tok) │ │ archival_memory (BGE) │ │ │ │ └── Slicing │ │ handoffs (embeddings) │ │ │ └────────────────────────┘ └────────────────────────┘ │ │ ~1,200 tokens │ │ vs 23,000 raw │ │ = 95% savings FILE SYSTEM │ │ ┌────────────────────────┐ │ │ │ thoughts/ │ │ │ │ ├── ledgers/ │ │ │ │ │ └── CONTINUITY_*.md│ │ │ │ └── shared/ │ │ │ │ ├── handoffs/*.yaml│ │ │ │ └── plans/*.md │ │ │ │ │ │ │ │ .tldr/ │ │ │ │ └── (daemon cache) │ │ │ └────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Core Systems ### Skills System Skills are modular capabilities triggered by natural language. Located in `.claude/skills/`. #### Meta-Skills (Workflow Orchestrators) | Meta-Skill | Chain | Use When | |------------|-------|----------| | `/workflow` | Router → appropriate workflow | Don't know where to start | | `/build` | discovery → plan → validate → implement → commit | Building features | | `/fix` | sleuth → premortem → kraken → test → commit | Fixing bugs | | `/tdd` | plan → arbiter (tests) → kraken (implement) → arbiter | Test-first development | | `/refactor` | phoenix → plan → kraken → reviewer → arbiter | Safe code transformation | | `/review` | parallel specialized reviews → synthesis | Code review | | `/explore` | scout (quick/deep/architecture) | Understand codebase | | `/security` | vulnerability scan → verification | Security audits | | `/release` | audit → E2E → review → changelog | Ship releases | #### Meta-Skill Reference Each meta-skill supports modes, scopes, and flags. Type the skill alone (e.g., `/build`) to get an interactive question flow. **`/build <mode> [options] [description]`** | Mode | Chain | Use For | |------|-------|---------| | `greenfield` | discovery → plan → validate → implement → commit → PR | New feature from scratch | | `brownfield` | onboard → research → plan → validate → implement | Feature in existing codebase | | `tdd` | plan → test-first → implement | Test-driven development | | `refactor` | impact analysis → plan → TDD → implement | Safe refactoring | | Option | Effect | |--------|--------| | `--skip-discovery` | Skip interview phase (have clear spec) | | `--skip-validate` | Skip plan validation | | `--skip-commit` | Don't auto-commit | | `--skip-pr` | Don't create PR description | | `--parallel` | Run research agents in parallel | **`/fix <scope> [options] [description]`** | Scope | Chain | Use For | |-------|-------|---------| | `bug` | debug → implement → test → commit | General bug fix | | `hook` | debug-hooks → hook-developer → implement → test | Hook issues | | `deps` | preflight → oracle → plan → implement → qlty | Dependency errors | | `pr-comments` | github-search → research → plan → implement → commit | PR feedback | | Option | Effect | |--------|--------| | `--no-test` | Skip regression test | | `--dry-run` | Diagnose only, don't fix | | `--no-commit` | Don't auto-commit | **`/explore <depth> [options]`** | Depth | Time | What It Does | |-------|------|--------------| | `quick` | ~1 min | tldr tree + structure overview | | `deep` | ~5 min | onboard + tldr + research + documentation | | `architecture` | ~3 min | tldr arch + call graph + layers | | Option | Effect | |--------|--------| | `--focus "area"` | Focus on specific area (e.g., `--focus "auth"`) | | `--output handoff` | Create handoff for implementation | | `--output doc` | Create documentation file | | `--entry "func"` | Start from specific entry point | **`/tdd`, `/refactor`, `/review`, `/security`, `/release`** These follow their defined chains without mode flags. Just run: ``` /tdd "implement retry logic" /refactor "extract auth module" /review # reviews current changes /security "authentication code" /release v1.2.0 ``` #### Key Skills (High-Value Tools) **Planning & Risk** - **premortem**: TIGERS & ELEPHANTS risk analysis - use before any significant implementation - **discovery-interview**: Transform vague ideas into detailed specs **Context Management** - **create_handoff**: Capture session state for transfer - **resume_handoff**: Resume from handoff with context - **continuity_ledger**: Track state within session **Code Analysis (95% Token Savings)** - **tldr-code**: Call graph, CFG, DFG, slicing - **ast-grep-find**: Structural code search - **morph-search**: Fast text search (20x faster than grep) **Research** - **perplexity-search**: AI-powered web search - **nia-docs**: Library documentation search - **github-search**: Search GitHub code/issues/PRs **Quality** - **qlty-check**: 70+ linters, auto-fix - **braintrust-analyze**: Session analysis, replay, and debugging failed sessions **Math & Formal Proofs** - **math**: Unified computation (SymPy, Z3, Pint) — one entry point for all math - **prove**: Lean4 theorem proving with 5-phase workflow (Research → Design → Test → Implement → Verify) - **pint-compute**: Unit-aware arithmetic and conversions - **shapely-compute**: Computational geometry The `/prove` skill enables machine-verified proofs without learning Lean syntax. Used to create the first Lean formalization of Sylvester-Gallai theorem. #### The Thought Process ``` What do I want to do? ├── Don't know → /workflow (guided router) ├── Building → /build greenfield or brownfield ├── Fixing → /fix bug ├── Understanding → /explore ├── Planning → premortem first, then plan-agent ├── Researching → oracle or perplexity-search ├── Reviewing → /review ├── Proving → /prove (Lean4 formal verification) ├── Computing → /math (SymPy, Z3, Pint) └── Shipping → /release ``` [See detailed skills breakdown →](docs/skills/) --- ### Agents System Agents are specialized AI workers spawned via the Task tool. Located in `.claude/agents/`. #### Agent Categories (32 active) > **Note:** There are likely too many agents—consolidation is a v4 goal. Use what fits your workflow. **Orchestrators (2)** - **maestro**: Multi-agent coordination with patterns (Pipeline, Swarm, Jury) - **kraken**: TDD implementation agent with checkpoint/resume support **Planners (4)** - **architect**: Feature planning + API integration - **phoenix**: Refactoring + framework migration planning - **plan-agent**: Lightweight planning with research/MCP tools - **validate-agent**: Validate plans against best practices **Explorers (4)** - **scout**: Codebase exploration (use instead of Explore) - **oracle**: External research (web, docs, APIs) - **pathfinder**: External repository analysis - **research-codebase**: Document codebase as-is **Implementers (3)** - **kraken**: TDD implementation with strict test-first workflow - **spark**: Lightweight fixes and quick tweaks - **agentica-agent**: Build Python agents using Agentica SDK **Debuggers (3)** - **sleuth**: General bug investigation and root cause - **debug-agent**: Issue investigation via logs/code search - **profiler**: Performance profiling and race conditions **Validators (2)** - arbiter, atlas **Reviewers (6)** - critic, judge, surveyor, liaison, plan-reviewer, review-agent **Specialized (8)** - aegis, herald, scribe, chronicler, session-analyst, braintrust-analyst, memory-extractor, onboard #### Common Workflows | Workflow | Agent Chain | |----------|-------------| | Feature | architect → plan-reviewer → kraken → review-agent → arbiter | | Refactoring | phoenix → plan-reviewer → kraken → judge → arbiter | | Bug Fix | sleuth → spark/kraken → arbiter → scribe | [See detailed agent guide →](docs/agents/) --- ### Hooks System Hooks intercept Claude Code at lifecycle points. Located in `.claude/hooks/`. #### Hook Events (30 hooks total) | Event | Key Hooks | Purpose | |-------|-----------|---------| | **SessionStart** | session-start-continuity, session-register, braintrust-tracing | Load context, register session | | **PreToolUse** | tldr-read-enforcer, smart-search-router, tldr-context-inject, file-claims | Token savings, search routing | | **PostToolUse** | post-edit-diagnostics, handoff-index, post-edit-notify | Validation, indexing | | **PreCompact** | pre-compact-continuity | Auto-save before compaction | | **UserPromptSubmit** | skill-activation-prompt, memory-awareness | Skill hints, memory recall | | **SubagentStop** | subagent-stop-continuity | Save agent state | | **SessionEnd** | session-end-cleanup, session-outcome | Cleanup, extract learnings | #### Key Hooks | Hook | Purpose | |------|---------| | **tldr-context-inject** | Adds code analysis to agent prompts | | **smart-search-router** | Routes grep to AST-grep when appropriate | | **post-edit-diagnostics** | Runs pyright/ruff after edits | | **memory-awareness** | Surfaces relevant learnings | [See all 30 hooks →](docs/hooks/) --- ### TLDR Code Analysis TLDR provides token-efficient code summaries through 5 analysis layers. #### The 5-Layer Stack | Layer | Name | What it provides | Tokens | |-------|------|------------------|--------| | **L1** | AST | Functions, classes, signatures | ~500 tokens | | **L2** | Call Graph | Who calls what (cross-file) | +440 tokens | | **L3** | CFG | Control flow, complexity | +110 tokens | | **L4** | DFG | Data flow, variable tracking | +130 tokens | | **L5** | PDG | Program slicing, impact analysis | +150 tokens | **Total: ~1,200 tokens vs 23,000 raw = 95% savings** #### CLI Commands ```bash # Structure analysis tldr tree src/ # File tree tldr structure src/ --lang python # Code structure (codemaps) # Search and extraction tldr search "process_data" src/ # Find code tldr context process_data --project src/ --depth 2 # LLM-ready context # Flow analysis tldr cfg src/main.py main # Control flow graph tldr dfg src/main.py main # Data flow graph tldr slice src/main.py main 42 # What affects line 42? # Codebase analysis tldr impact process_data src/ # Who calls this function? tldr dead src/ # Find unreachable code tldr arch src/ # Detect architectural layers # Semantic search (natural language) tldr daemon semantic "find authentication logic" ``` #### Semantic Index Beyond structural analysis, TLDR builds a **semantic index** of your codebase: - **Natural language queries** — Ask "where is error handling?" instead of grepping - **Auto-rebuild** — Dirty flag hook tracks file changes; index rebuilds after N edits - **Selective indexing** — Use `.tldrignore` to control what gets indexed ```bash # .tldrignore example __pycache__/ *.test.py node_modules/ .venv/ ``` The semantic index uses all 5 layers plus 10 lines of surrounding code context—not just docstrings. #### Hook Integration TLDR is automatically integrated via hooks: - **tldr-read-enforcer**: Returns L1+L2+L3 instead of full file reads - **smart-search-router**: Routes Grep to `tldr search` - **post-tool-use-tracker**: Updates indexes when files change [See TLDR documentation →](opc/packages/tldr-code/) --- ### Memory System Cross-session learning powered by PostgreSQL + pgvector. #### How It Works ``` Session ends → Database detects stale heartbeat (>5 min) → Daemon spawns headless Claude (Sonnet) → Analyzes thinking blocks from session → Extracts learnings to archival_memory → Next session recalls relevant learnings ``` The key insight: **thinking blocks contain the real reasoning**—not just what Claude did, but why. The daemon extracts this automatically. #### Conversational Interface | What You Say | What Happens | |--------------|--------------| | "Remember that auth uses JWT" | Stores learning with context | | "Recall authentication patterns" | Searches memory, surfaces matches | | "What did we decide about X?" | Implicit recall via memory-awareness hook | #### Database Schema (4 tables) | Table | Purpose | |-------|---------| | **sessions** | Cross-terminal awareness | | **file_claims** | Cross-terminal file locking | | **archival_memory** | Long-term learnings with BGE embeddings | | **handoffs** | Session handoffs with embeddings | #### Recall Commands ```bash # Recall learnings (hybrid text + vector search) cd opc && uv run python scripts/core/recall_learnings.py \ --query "authentication patterns" # Store a learning explicitly cd opc && uv run python scripts/core/store_learning.py \ --session-id "my-session" \ --type WORKING_SOLUTION \ --content "What I learned" \ --confidence high ``` #### Automatic Memory The **memory-awareness** hook surfaces relevant learnings when you send a message. You'll see `MEMORY MATCH` indicators—Claude can use these without you asking. --- ### Continuity System Preserve state across context clears and sessions. #### Continuity Ledger Within-session state tracking. Location: `thoughts/ledgers/CONTINUITY_<topic>.md` ```markdown # Session: feature-x Updated: 2026-01-08 ## Goal Implement feature X with proper error handling ## Completed - [x] Designed API schema - [x] Implemented core logic ## In Progress - [ ] Add error handling ## Blockers - Need clarification on retry policy ``` #### Handoffs Between-session knowledge transfer. Location: `thoughts/shared/handoffs/<session>/` ```yaml --- date: 2026-01-08T15:26:01+0000 session_name: feature-x status: complete --- # Handoff: Feature X Implementation ## Task(s) | Task | Status | |------|--------| | Design API | Completed | | Implement core | Completed | | Error handling | Pending | ## Next Steps 1. Add retry logic to API calls 2. Write integration tests ``` #### Commands | Command | Effect | |---------|--------| | "save state" | Updates continuity ledger | | "done for today" / `/handoff` | Creates handoff document | | "resume work" | Loads latest handoff | --- ### Math System Two capabilities: **computation** (SymPy, Z3, Pint) and **formal verification** (Lean4 + Mathlib). #### The Stack | Tool | Purpose | Example | |------|---------|---------| | **SymPy** | Symbolic math | Solve equations, integrals, matrix operations | | **Z3** | Constraint solving | Prove inequalities, SAT problems | | **Pint** | Unit conversion | Convert miles to km, dimensional analysis | | **Lean4** | Formal proofs | Machine-verified theorems | | **Mathlib** | 100K+ theorems | Pre-formalized lemmas to build on | | **Loogle** | Type-aware search | Find Mathlib lemmas by signature | #### Two Entry Points | Skill | Use When | |-------|----------| | `/math` | Computing, solving, calculating | | `/prove` | Formal verification, machine-checked proofs | #### /math Examples ```bash # Solve equation "Solve x² - 4 = 0" → x = ±2 # Compute eigenvalues "Eigenvalues of [[2,1],[1,2]]" → {1: 1, 3: 1} # Prove inequality "Is x² + y² ≥ 2xy always true?" → PROVED (equals (x-y)²) # Convert units "26.2 miles to km" → 42.16 km ``` #### /prove - Formal Verification 5-phase workflow for machine-verified proofs: ``` 📚 RESEARCH → 🏗️ DESIGN → 🧪 TEST → ⚙️ IMPLEMENT → ✅ VERIFY ``` 1. **Research**: Search Mathlib with Loogle, find proof strategy 2. **Design**: Create skeleton with `sorry` placeholders 3. **Test**: Search for counterexamples before proving 4. **Implement**: Fill sorries with compiler-in-the-loop feedback 5. **Verify**: Audit axioms, confirm zero sorries ``` /prove every group homomorphism preserves identity /prove continuous functions on compact sets are uniformly continuous ``` **Achievement**: Used to create the first Lean formalization of the Sylvester-Gallai theorem. #### Prerequisites (Optional) Math features require installation via wizard step 9: ```bash # Installed automatically by wizard uv pip install sympy z3-solver pint shapely # Lean4 (for /prove) curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh ``` --- ## Workflows ### /workflow - Goal-Based Router ``` > /workflow ? What's your goal? ○ Research - Understand codebase/docs ○ Plan - Design implementation approach ○ Build - Implement features ○ Fix - Investigate and resolve issues ``` ### /fix - Bug Resolution ```bash /fix bug "login fails silently" ``` **Chain:** sleuth → [checkpoint] → [premortem] → kraken → test → commit | Scope | What it does | |-------|--------------| | `bug` | General bug investigation | | `hook` | Hook-specific debugging | | `deps` | Dependency issues | | `pr-comments` | Address PR feedback | ### /build - Feature Development ```bash /build greenfield "user dashboard" ``` **Chain:** discovery → plan → validate → implement → commit → PR | Mode | What it does | |------|--------------| | `greenfield` | New feature from scratch | | `brownfield` | Modify existing codebase | | `tdd` | Test-first development | | `refactor` | Safe code transformation | ### /premortem - Risk Analysis ```bash /premortem deep thoughts/shared/plans/feature-x.md ``` **Output:** - **TIGERS**: Clear threats (HIGH/MEDIUM/LOW severity) - **ELEPHANTS**: Unspoken concerns Blocks on HIGH severity until user accepts/mitigates risks. --- ## Installation ### Full Installation (Recommended) ```bash # Clone git clone https://github.com/parcadei/continuous-claude.git cd continuous-claude/opc # Run the setup wizard uv run python -m scripts.setup.wizard ``` The wizard walks you through all configuration options interactively. ## Updating Pull latest changes and sync your installation: ```bash cd continuous-claude/opc uv run python -m scripts.setup.update ``` This will: - Pull latest from GitHub - Update hooks, skills, rules, agents - Upgrade TLDR if installed - Rebuild TypeScript hooks if changed ### What Gets Installed | Component | Location | |-----------|----------| | Agents (32) | ~/.claude/agents/ | | Skills (109) | ~/.claude/skills/ | | Hooks (30) | ~/.claude/hooks/ | | Rules | ~/.claude/rules/ | | Scripts | ~/.claude/scripts/ | | PostgreSQL | Docker container | ### Installation Mode: Copy vs Symlink The wizard offers two installation modes: | Mode | How It Works | Best For | |------|--------------|----------| | **Copy** (default) | Copies files from repo to `~/.claude/` | End users, stable setup | | **Symlink** | Creates symlinks to repo files | Contributors, development | #### Copy Mode (Default) Files are copied from `continuous-claude/.claude/` to `~/.claude/`. Changes you make in `~/.claude/` are **local only** and will be overwritten on next update. ```text continuous-claude/.claude/ ──COPY──> ~/.claude/ (source) (user config) ``` **Pros:** Stable, isolated from repo changes **Cons:** Local changes lost on update, manual sync needed #### Symlink Mode (Recommended for Contributors) Creates symlinks so `~/.claude/` points directly to repo files. Changes in either location affect the same files. ```text ~/.claude/rules ──SYMLINK──> continuous-claude/.claude/rules ~/.claude/skills ──SYMLINK──> continuous-claude/.claude/skills ~/.claude/hooks ──SYMLINK──> continuous-claude/.claude/hooks ~/.claude/agents ──SYMLINK──> continuous-claude/.claude/agents ``` **Pros:** - Changes auto-sync to repo (can `git commit` improvements) - No re-installation needed after `git pull` - Contribute back easily **Cons:** - Breaking changes in repo affect your setup immediately - Need to manage git workflow #### Switching to Symlink Mode If you installed with copy mode and want to switch: ```bash # Backup current config mkdir -p ~/.claude/backups/$(date +%Y%m%d) cp -r ~/.claude/{rules,skills,hooks,agents} ~/.claude/backups/$(date +%Y%m%d)/ # Verify backup succeeded before proceeding ls -la ~/.claude/backups/$(date +%Y%m%d)/ # Remove copies (only after verifying backup above) rm -rf ~/.claude/{rules,skills,hooks,agents} # Create symlinks (adjust path to your repo location) REPO="$HOME/continuous-claude" # or wherever you cloned ln -s "$REPO/.claude/rules" ~/.claude/rules ln -s "$REPO/.claude/skills" ~/.claude/skills ln -s "$REPO/.claude/hooks" ~/.claude/hooks ln -s "$REPO/.claude/agents" ~/.claude/agents # Verify ls -la ~/.claude | grep -E "rules|skills|hooks|agents" ``` **Windows users:** Use PowerShell (as Administrator or with Developer Mode enabled): ```powershell # Enable Developer Mode first (Settings → Privacy & security → For developers) # Or run PowerShell as Administrator # Backup current config $BackupDir = "$HOME\.claude\backups\$(Get-Date -Format 'yyyyMMdd')" New-Item -ItemType Directory -Path $BackupDir -Force Copy-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" $BackupDir # Verify backup succeeded before proceeding Get-ChildItem $BackupDir # Remove copies (only after verifying backup above) Remove-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" # Create symlinks (adjust path to your repo location) $REPO = "$HOME\continuous-claude" # or wherever you cloned New-Item -ItemType SymbolicLink -Path "$HOME\.claude\rules" -Target "$REPO\.claude\rules" New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills" -Target "$REPO\.claude\skills" New-Item -ItemType SymbolicLink -Path "$HOME\.claude\hooks" -Target "$REPO\.claude\hooks" New-Item -ItemType SymbolicLink -Path "$HOME\.claude\agents" -Target "$REPO\.claude\agents" # Verify Get-ChildItem "$HOME\.claude" | Where-Object { $_.LinkType -eq "SymbolicLink" } ``` ### For Brownfield Projects After installation, start Claude and run: ``` > /onboard ``` This analyzes the codebase and creates an initial continuity ledger. --- ## Configuration ### .claude/settings.json Central configuration for hooks, tools, and workflows. ```json { "hooks": { "SessionStart": [...], "PreToolUse": [...], "PostToolUse": [...], "UserPromptSubmit": [...] } } ``` ### .claude/skills/skill-rules.json Skill activation triggers. ```json { "rules": [ { "skill": "fix", "keywords": ["fix this", "broken", "not working"], "intentPatterns": ["fix.*(bug|issue|error)"] } ] } ``` ### Environment Variables | Variable | Purpose | Required | |----------|---------|----------| | `DATABASE_URL` | PostgreSQL connection string | Yes | | `BRAINTRUST_API_KEY` | Session tracing | No | | `PERPLEXITY_API_KEY` | Web search | No | | `NIA_API_KEY` | Documentation search | No | | `CLAUDE_OPC_DIR` | Path to CC's opc/ directory (set by wizard) | Auto | | `CLAUDE_PROJECT_DIR` | Current project directory (set by SessionStart hook) | Auto | Services without API keys still work: - Continuity system (ledgers, handoffs) - TLDR code analysis - Local git operations - TDD workflow --- ## Directory Structure ``` continuous-claude/ ├── .claude/ │ ├── agents/ # 32 specialized AI agents │ ├── hooks/ # 30 lifecycle hooks │ │ ├── src/ # TypeScript source │ │ └── dist/ # Compiled JavaScript │ ├── skills/ # 109 modular capabilities │ ├── rules/ # System policies │ ├── scripts/ # Python utilities │ └── settings.json # Hook configuration ├── opc/ │ ├── packages/ │ │ └── tldr-code/ # 5-layer code analysis │ ├── scripts/ │ │ ├── setup/ # Wizard, Docker, integration │ │ └── core/ # recall_learnings, store_learning │ └── docker/ │ └── init-schema.sql # 4-table PostgreSQL schema ├── thoughts/ │ ├── ledgers/ # Continuity ledgers (CONTINUITY_*.md) │ └── shared/ │ ├── handoffs/ # Session handoffs (*.yaml) │ └── plans/ # Implementation plans └── docs/ # Documentation ``` --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: - Adding new skills - Creating agents - Developing hooks - Extending TLDR --- ## Acknowledgments ### Patterns & Architecture - **[@numman-ali](https://github.com/numman-ali)** - Continuity ledger pattern - **[Anthropic](https://anthropic.com)** - Claude Code and "Code Execution with MCP" - **[obra/superpowers](https://github.com/obra/superpowers)** - Agent orchestration patterns - **[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)** - Compound engineering workflow - **[yoloshii/mcp-code-execution-enhanced](https://github.com/yoloshii/mcp-code-execution-enhanced)** - Enhanced MCP execution - **[HumanLayer](https://github.com/humanlayer/humanlayer)** - Agent patterns ### Tools & Services - **[uv](https://github.com/astral-sh/uv)** - Python packaging - **[tree-sitter](https://tree-sitter.github.io/)** - Code parsing - **[Braintrust](https://braintrust.dev)** - LLM evaluation, logging, and session tracing - **[qlty](https://github.com/qltysh/qlty)** - Universal code quality CLI (70+ linters) - **[ast-grep](https://github.com/ast-grep/ast-grep)** - AST-based code search and refactoring - **[Nia](https://trynia.ai)** - Library documentation search - **[Morph](https://www.morphllm.com)** - WarpGrep fast code search - **[Firecrawl](https://www.firecrawl.dev)** - Web scraping API - **[RepoPrompt](https://repoprompt.com)** - Token-efficient codebase maps --- ## Star History [](https://star-history.com/#parcadei/Continuous-Claude-v2&Date) --- ## License [MIT](LICENSE) - Use freely, contribute back. --- **Continuous Claude**: Not just a coding assistant—a persistent, learning, multi-agent development environment that gets smarter with every session.