Introduction & Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
Continuous Claude is a session management and execution framework for Claude Code designed to overcome the lossy nature of LLM context compaction. The system operates on the core philosophy that clearing context is superior to compacting it, provided that state is preserved in external high-fidelity "ledgers" and "handoffs." By maintaining state outside the active conversation, the project ensures that Claude can work with full context fidelity even after multiple session resets.
Sources: CLAUDE_ONBOARDING.md:12-25, CLAUDE.md:144-147
The project prioritizes "Local-First" operations, providing offline alternatives for every supported paid service (such as Firecrawl, Morph, and Braintrust). It implements a high-efficiency MCP (Model Context Protocol) runtime that achieves up to a 99.6% reduction in token overhead by utilizing reusable Python scripts with CLI arguments rather than writing novel code for every tool call.
Sources: CLAUDE_ONBOARDING.md:8-10, CLAUDE.md:6-10, scripts/README.md:5-7
Core Philosophies
Clear > Compact
The primary architectural driver is the belief that Claude Code's native context compaction leads to degraded reasoning over time (a "summary of a summary"). Continuous Claude solves this by encouraging users to /clear the session whenever context usage reaches high thresholds (typically 70%+), after first persisting the state to a markdown ledger.
Sources: CLAUDE_ONBOARDING.md:19-25, CLAUDE_ONBOARDING.md:144-146
Reusable Capabilities
Anthropic’s vision of agents building a toolbox of reusable capabilities is implemented through the Scripts Framework. Developers are encouraged to discover and execute existing scripts via CLI arguments rather than editing script logic to change parameters. This separation of logic and parameters minimizes file-write operations and token usage.
Sources: scripts/SCRIPTS.md:3-9, scripts/SCRIPTS.md:44-55
Local-First & Zero-Trust Architecture
The system is designed to run 100% offline. While it supports cloud-based MCP servers and tracking tools like Braintrust, it provides local-first hooks and databases to maintain performance and privacy without requiring API keys.
Sources: CLAUDE_ONBOARDING.md:8-10, install-global.sh:445-475, scripts/README.md:31-40
System Lifecycle & Session Flow
The lifecycle of a Continuous Claude session is defined by the transition between active work and state persistence. The following diagram illustrates the standard session loop.
The session starts by reloading the state from permanent markdown files, proceeds through task execution, and triggers a manual context reset once token limits are reached.
Sources: CLAUDE_ONBOARDING.md:27-32, CLAUDE_ONBOARDING.md:144-147
Project Structure & Directory Mapping
The project differentiates between internal framework components, ephemeral session data, and permanent project memory.
| Directory | Purpose | Retention |
|---|---|---|
.claude/skills/ | Claude Code native skill definitions (SKILL.md) | Permanent |
scripts/ | Agent-agnostic CLI Python workflows | Permanent |
thoughts/handoff/ | Cross-session task handoffs | Permanent |
thoughts/ledgers/ | Active session state snapshots | Ephemeral/Updated |
.claude/cache/ | Search indexes and local databases | Local/Ignored |
Sources: CLAUDE_ONBOARDING.md:46-56, init-project.sh:110-128, scripts/README.md:16-25
Execution Strategies
Continuous Claude utilizes a dual-mode execution pattern for MCP tools, prioritizing efficiency through the filesystem.
Primary: Scripts-Based Execution
This is the preferred method for complex workflows. Instead of Claude writing Python code to call tools, it finds an existing script in ./scripts/ and executes it with uv run python -m runtime.harness. This method provides a 99.6% token reduction.
Sources: CLAUDE.md:6-10, scripts/SCRIPTS.md:44-55
Alternative: Direct Script Writing
Used only for novel tasks where no template exists. Claude explores servers/ to find tool definitions and writes a one-off script. This is considered less efficient (~2,000 tokens vs 110 tokens) but necessary for prototyping.
Sources: CLAUDE.md:82-90, scripts/SCRIPTS.md:86-95
Efficiency Comparison
| Method | Tokens | Time | Purpose |
|---|---|---|---|
| CLI Execution | ~110 | ~5s | Reusing established workflows |
| Editing Scripts | ~800 | ~30s | Fixing bugs or logic |
| Writing Scratch | ~5,000 | ~2m | New, unique tool chains |
Sources: scripts/SCRIPTS.md:44-55
Core Development Patterns
The project follows strict patterns for state management and skill extension:
- Parameter Immutability: Parameters are passed via CLI arguments (argparse), never by modifying source files.
- Logic Mutability: Developers are encouraged to edit script logic to improve functionality or fix bugs.
- Hierarchical Memory: Uses
claude-memfor vector/FTS5 search across sessions andartifact_index.pyto index markdown handoffs into a local SQLite Context Graph. - Hook Pattern: Shell wrappers trigger TypeScript handlers for events like
SessionStartandPostToolUse.
Sources: CLAUDE_ONBOARDING.md:104-122, CLAUDE.md:155-175, scripts/artifact_index.py:1-25
Conclusion
Continuous Claude represents a shift from "conversational AI" to "agentic engineering." By treating context as an ephemeral workspace and markdown files as the source of truth, the framework allows for long-running, complex software engineering tasks that would otherwise exceed the reliable reasoning limits of current LLMs. Its focus on CLI-driven script execution and local-first data ensures both cost efficiency and operational stability.
Sources: CLAUDE_ONBOARDING.md:144-150, scripts/SCRIPTS.md:118-125