Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
Continuous Claude is a session management system designed for Claude Code that preserves state across sessions and reduces Model Context Protocol (MCP) token overhead. The system is designed to run 100% offline, providing local alternatives for all external services to ensure core functionality without requiring API keys.
Sources: CLAUDE_ONBOARDING.md:1-13, install-global.sh:448-450
The installation process involves two primary phases: a global system-wide setup of core components and a per-project initialization to establish the necessary directory structures and local databases for state tracking.
Sources: install-global.sh:1-10, init-project.sh:1-10
Global Installation
The global installation script (install-global.sh) handles the deployment of the Continuous Claude environment to the user's home directory (~/.claude). It automates the detection of the operating system (Linux, macOS, or Windows via WSL/Git Bash) and manages required dependencies.
Sources: install-global.sh:7-15, install-global.sh:105-140
Prerequisites & Dependency Management
The system requires several core components to function, primarily the uv Python package manager and Node.js. The installer attempts to auto-install these using available package managers like apt, brew, pacman, dnf, or winget.
Sources: install-global.sh:170-195, install-global.sh:230-250
| Component | Role | Required |
|---|---|---|
uv | Python package manager for MCP runtime | Yes |
Node.js | Required for session hooks | Yes |
npm | Required for MCP server management | Yes |
qlty | Local code quality toolkit | Optional |
repomix | Local codebase packing (replaces RepoPrompt) | Optional |
trafilatura | Local web scraping (replaces Firecrawl) | Optional |
claude-mem | Cross-session memory (replaces Braintrust) | Optional |
| Sources: install-global.sh:290-330, install-global.sh:454-474 |
Global Directory Structure
Once installed, the global configuration resides in ~/.claude/ with the following structure:
~/.claude/
├── agents/ # Sub-agent configurations
├── hooks/ # Event handlers (SessionStart, PostToolUse, etc.)
├── rules/ # Behavioral rules
├── scripts/ # Python workflow scripts
├── servers/ # MCP wrappers (e.g., qlty)
├── settings.json # Hook registrations
└── .env # API keys and environment variables
Sources: CLAUDE_ONBOARDING.md:46-55, install-global.sh:386-410
Installation Workflow
The following diagram illustrates the sequence of actions performed by the global installer:
The installer first ensures the environment is capable, then deploys the execution runtime and local configuration files.
Sources: install-global.sh:345-445
Project Initialization
After the global setup, each development project must be initialized using the init-project.sh script. This establishes the "thoughts" architecture required for continuous context.
Sources: init-project.sh:1-12
Initialization Modes
The script supports two distinct modes for handling project state:
- Fresh Mode: Creates a new, standalone
thoughts/directory within the project. - Monorepo Mode: Detects a parent directory with existing
thoughts/and creates a symlink to share state across sub-projects.
Sources: init-project.sh:86-135
Local State Components
Initialization creates several directories and a local database:
thoughts/ledgers/: Git-tracked continuity ledgers.thoughts/shared/handoffs/: Session-to-session state files.thoughts/shared/plans/: Implementation plans..claude/cache/artifact-index/context.db: A local SQLite database used for indexing artifacts for fast retrieval.
Sources: init-project.sh:137-185, CLAUDE_ONBOARDING.md:33-40
The project structure separates local-only cache (gitignored) from permanent reasoning artifacts (git-tracked).
Sources: init-project.sh:210-225, CLAUDE_ONBOARDING.md:54-57
Core Operational Workflow
Continuous Claude operates by intercepting Claude Code events via hooks and providing a "ledger" system to prevent context degradation.
Sources: CLAUDE_ONBOARDING.md:19-24
Session Lifecycle
The system manages context by clearing and reloading state rather than allowing lossy compaction.
Sources: CLAUDE_ONBOARDING.md:28-31
The lifecycle ensures that reasoning is preserved in external files, allowing for a clean slate when the LLM context fills up.
Sources: CLAUDE_ONBOARDING.md:28-31, CLAUDE.md:210-220
Execution Commands
Once installed and initialized, the following commands are used to manage the environment:
| Command | Purpose |
|---|---|
uv run mcp-generate | Generates Python wrappers from MCP configurations |
uv run mcp-exec <script> | Runs a Python script with MCP tool access |
~/.claude/scripts/init-project.sh | Initializes a new project (global location) |
/continuity_ledger | Claude Code command to save session state |
| Sources: CLAUDE.md:65-75, init-project.sh:230-235, CLAUDE_ONBOARDING.md:65-70 |
Summary
Getting started with Continuous Claude requires a one-time global installation to set up the MCP runtime and local-first tools, followed by per-project initialization to enable state tracking. This architecture allows developers to maintain high-fidelity context over long-running sessions by utilizing markdown-based ledgers and local SQLite indexing, all while operating entirely offline.
Sources: CLAUDE_ONBOARDING.md:10-15, install-global.sh:448-455, init-project.sh:205-220