█▀▀ █▀█ █▄ █ ▀█▀ █ █▄ █ █ █ █ █ █▀▄▀█
█▄▄ █▄█ █ ▀█ █ █ █ ▀█ █▄█ █▄█ █ ▀ █
An open-source engineering engine that captures, verifies, and packages your project state for seamless continuity across AI coding assistants and models such as Claude, GPT, Gemini, Cursor, Antigravity, Local LLMs, etc.
[01] Extract Physical State ──► [02] Arbitrate Ground Truth ──► [03] Build State DAG ──► [04] Package Handoff
 |
 |
 |
 |
 |
 |
 |
 |
# SYSTEM NAVIGATION MAP ├── [01] FOUNDATION & BENCHMARK │ ├── ❯ Overview & Core Problem │ ├── ❯ 🌟 LATEST: What's New in v1.4.0 (Universal Work Continuity & Resume Center) │ ├── ❯ Benchmark: Continuum vs Chat Summaries │ └── ❯ 1-Command Quickstart Guide │ ├── [02] ARCHITECTURE & GROUND TRUTH │ ├── ❯ 3-State Separation Engine │ ├── ❯ 5-Tier Evidence Arbitration Matrix │ └── ❯ Canonical Dependency Graph (DAG) │ └── [03] TOOLING & GOVERNANCE ├── ❯ Omni-Model Handoff Adapters ├── ❯ Complete CLI Command Reference ├── ❯ Architecture & Verification ├── ❯ Testing & Verification ├── ❯ Contributing Guide ├── ❯ Code of Conduct ├── ❯ Security & Privacy └── ❯ License
Continuum is an open-source work continuity platform for multi-agent software engineering. It automatically extracts, arbitrates, and packages verified workspace state — enabling seamless, zero-drift handoffs across Claude, GPT-4o, Gemini, Cursor, and local LLMs.
| Feature Pillar | Architecture & Capabilities |
|---|---|
| 🏛️ 3-State Engine | Strict ontological separation between Project State (AST symbols, files, tests), Conversational State (requirements, chat claims), and Agent Execution State (in-flight edits). |
| ⚖️ 5-Tier Truth Matrix | Proof-grounded arbitration engine. When conversational claims conflict with codebase reality, physical evidence strictly takes precedence with automated contradiction logging. |
| 🕸️ State Graph (DAG) | Topological Directed Acyclic Graph connecting milestones to code symbols. Automatically propagates STALE invalidations downstream when files change. |
| 🤖 Omni-Model Handoff | Single-command generation of model-native context packages tailored for Claude (XML tagged), GPT/Codex, Gemini, and Local LLMs. |
| 🛡️ Autonomous Governance | Background observer daemon paired with non-blocking Git commit hooks, SHA-256 state provenance, corruption self-healing, and 100% local zero telemetry. |
Continuum v1.4.0 introduces the Universal Resume Anywhere engine (Milestones 35–46, Phases 50–87). It turns Continuum into a complete, local-first work continuity platform that tracks partitioned activities, captures durable checkpoints with provenance, generates deterministic resume briefs, enables visual timeline diffing, non-destructive branching, and instant offline full-text search across thousands of records.
| v1.4.0 Core Pillar | Technical Architecture & Capabilities |
|---|---|
| ⚡ Universal Resume Anywhere Engine (Milestones 35–37) |
Local-first lifecycle management and deterministic resume briefs:
|
| 🎛️ Interactive Web Dashboard & Timeline (Milestones 38–39) |
Modern browser control center launched with continuum serve:
|
| 🔍 SQLite FTS5 Local Search & Portability (Milestones 40–44) |
Instant, offline discoverability and cross-machine portability:
|
Conversational summaries degrade across sessions because they record what agents say, not what exists on disk. Continuum replaces subjective chat memory with verified codebase state.
[WITHOUT CONTINUUM]
Chat Logs ──► LLM Compression ──► Context Drift ──► Broken Agent Handoff ❌
[WITH CONTINUUM]
Workspace ──► AST & Test Proof ──► 5-Tier Truth ──► Seamless Omni-Handoff ✅
🔬 AST & Symbol Grounding
• Chat Summaries ░░░░░░░░░░ [0/10] (Zero Code Awareness)
• Custom Scripts ████░░░░░░ [4/10] (Regex / Naive Parsing)
• ⬢ CONTINUUM ██████████ [10/10] (Polyglot AST & Full Symbol Resolution)
⚖️ Contradiction Detection
• Chat Summaries ░░░░░░░░░░ [0/10] (Propagates Hallucinations)
• Custom Scripts ░░░░░░░░░░ [0/10] (No Conflict Ledger)
• ⬢ CONTINUUM ██████████ [10/10] (5-Tier Proof Arbitration)
🕸️ Dependency Graph (DAG)
• Chat Summaries ░░░░░░░░░░ [0/10] (Flat Text Memory)
• Custom Scripts █░░░░░░░░░ [1/10] (Ad-hoc File Lists)
• ⬢ CONTINUUM ██████████ [10/10] (Topological DAG & Stale Propagation)
📦 Omni-Model Handoffs
• Chat Summaries ██░░░░░░░░ [2/10] (Copy-Paste Prompts)
• Custom Scripts ████░░░░░░ [4/10] (Single-Model Output)
• ⬢ CONTINUUM ██████████ [10/10] (Claude, GPT-4o, Gemini, Local LLMs)
🛡️ State Self-Healing
• Chat Summaries ░░░░░░░░░░ [0/10] (Zero Recovery)
• Custom Scripts ░░░░░░░░░░ [0/10] (No Snapshots)
• ⬢ CONTINUUM ██████████ [10/10] (Snapshot History & Auto-Recovery)
⚡ 1-Command Workflow
• Chat Summaries █░░░░░░░░░ [1/10] (Manual Copy-Paste)
• Custom Scripts █████░░░░░ [5/10] (Custom Flags Required)
• ⬢ CONTINUUM ██████████ [10/10] (Smart Auto-Init & Auto-Scan)
# Install via PyPI
pip install continuum-toolkit
# Or install from source
git clone https://github.com/Ashish6298/CONTINUUM.git
cd CONTINUUM
pip install -e . █▀▀ █▀█ █▄ █ ▀█▀ █ █▄ █ █ █ █ █ █▀▄▀█
█▄▄ █▄█ █ ▀█ █ █ █ ▀█ █▄█ █▄█ █ ▀ █
AI Work Continuity & Cross-Model Agent Handoff System
─────────────────────────────────────────────────────────────────────────────
1. Terminal & IDE Coding Agents:
$ continuum handoff
• When to use: When your AI coding assistant (Claude Code, Cursor, Codex,
Antigravity) hits token limits, drifts from ground truth, or when you
want to switch to a different AI model without losing progress.
• Why to use: Automatically captures workspace state, extracts AST symbols,
and generates verified, model-tailored handoff prompt packages.
2. Web Browser AI Chats (ChatGPT, Claude, Gemini, DeepSeek, Local LLMs, etc.):
$ continuum setup --browser
• When to use: When using web chat AI interfaces and you run out of context,
hit token exhaustion, or want to continue the discussion in another AI.
• Why to use: 1-Click installer for the Continuum browser companion that
lets you extract conversations and inject them across AI tabs seamlessly.
3. Universal Work Continuity & Resume Center:
$ continuum serve
• When to use: When you want local-first, durable task tracking across
checkpoints, deterministic resume briefs, local full-text search,
and a full browser dashboard for your work.
• Why to use: Launches the offline Web Dashboard & Resume Center with
timeline diffs, branching, safe restore, and zero telemetry.
─────────────────────────────────────────────────────────────────────────────
v1.4.0 python 3.11.4 mit license github.com/Ashish6298/CONTINUUM
Run inside any project directory:
# 1-Click Browser Companion Setup (Opens Tampermonkey & Companion Installer)
continuum setup --browser
# Or launch local web dashboard & live REST API server
continuum serve- Dashboard UI: Open
http://127.0.0.1:8765in your browser. - In-Chat AI Injection: Press Alt+C on ChatGPT, Claude.ai, Gemini, or DeepSeek to extract conversations and inject them across tabs in 1-click.
Run inside any project directory — Continuum automatically scans your codebase, extracts AST symbols, builds the dependency graph, and creates your ready-to-resume AI handoff package:
continuum handoff◈ [HANDOFF READY] Generated Omni-Model Continuity Package:
Location: D:\myproject\ai_handoff
✦ Universal Handoff → D:\myproject\ai_handoff\handoff.md (Works for ANY model)
✦ Claude Optimized → D:\myproject\ai_handoff\claude_handoff.md
✦ GPT / Codex Plan → D:\myproject\ai_handoff\gpt_handoff.md
✦ Gemini Hierarchy → D:\myproject\ai_handoff\gemini_handoff.md
✦ Machine State → D:\myproject\ai_handoff\project-state.json
➤ [NEXT ACTION] Paste this prompt into your next AI Agent chat:
"Read ai_handoff/handoff.md and continue the project."
Continuum enforces strict separation between physical code truth and conversational assertions:
┌──────────────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────────┐
│ 01. PHYSICAL PROJECT STATE │ │ 02. CONVERSATIONAL STATE │ │ 03. AGENT EXECUTION STATE │
├──────────────────────────────┤ ├──────────────────────────────┤ ├──────────────────────────────┤
│ • Physical Source Code │ │ • User Intent & Goals │ │ • Active Tactical Task │
│ • Polyglot AST Symbol Tree │ │ • Architectural Decisions │ │ • In-Flight File Changes │
│ • Git Working Tree & Diffs │ │ • Agent Assertions & Claims │ │ • Transient Subprocess Logs │
│ • Test Suite Pass/Fail Logs │ │ • Unresolved Open Questions │ │ • Deterministic Next Action │
└──────────────┬───────────────┘ └──────────────┬───────────────┘ └──────────────┬───────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ⬢ CANONICAL STATE ENGINE (Topological DAG Graph) │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
When evidence sources conflict, Continuum arbitrates ground truth according to strict mathematical seniority:
┌─ [L1] RUNTIME EXECUTION ────────────────────────────────────────────────────────┐
│ Artifacts: TEST_RUN, BUILD_LOG, RUNTIME_LOG Weight: 100% │
│ Rule : Absolute ground truth. Real execution exit codes govern status. │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─ [L2] AST SYNTAX & FILES ───────────────────────────────────────────────────────┐
│ Artifacts: SOURCE_CODE, AST_SYMBOL, MANIFEST Weight: 90% │
│ Rule : Physical code exports override git commit messages and chat claims. │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─ [L3] VERSION CONTROL DELTAS ───────────────────────────────────────────────────┐
│ Artifacts: GIT_COMMIT, GIT_DIFF, GIT_STATUS Weight: 75% │
│ Rule : Historical changes override unverified comments and documentation. │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─ [L4] ARCHITECTURE DOCUMENTATION ───────────────────────────────────────────────┐
│ Artifacts: DOCUMENTATION, CODE_COMMENT Weight: 50% │
│ Rule : Informational context. Marked STALE when AST symbols change. │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─ [L5] CONVERSATIONAL AGENT CLAIMS ──────────────────────────────────────────────┐
│ Artifacts: CONVERSATION_ASSERTION, USER_REQUIREMENT Weight: 25% │
│ Rule : Unverified hypothesis until proven on disk by Levels 1-3. │
└─────────────────────────────────────────────────────────────────────────────────┘
Continuum models all milestones, phases, AST symbols, requirements, and test suites as a topologically ordered Directed Acyclic Graph:
[MILESTONE] Core Architecture ──► [PHASE 0] Canonical Schema
│
┌──────────────────────┴──────────────────────┐
▼ ▼
[SERVICE] StorageManager [SERVICE] AstExtractor
│ │
▼ ▼
[TEST] test_serialization.py [TEST] test_workspace_extractor.py
(Status: ✅ PASS) (Status: ✅ PASS)
┌─ GRAPH ENGINE CAPABILITIES ─────────────────────────────────────────────────────────────┐
│ • Topological Invalidation : Modifying a service automatically marks downstream tests │
│ and modules as STALE. │
│ • Cycle Detection & Guard : Circular dependency insertions (A -> B -> A) are blocked │
│ at graph construction time. │
│ • Subgraph Extraction : AI context selectors extract minimal task-relevant slices │
│ to stay within LLM token budgets. │
└─────────────────────────────────────────────────────────────────────────────────────────┘
Running continuum handoff compiles verified project state into 5 specialized model formats:
$ continuum handoff
│
├── 🌐 [UNIVERSAL] ──► handoff.md (Works for ANY model out of the box)
├── 🟣 [CLAUDE] ──► claude_handoff.md (Strict Anthropic XML tag hierarchy)
├── 🟢 [GPT/CODEX] ──► gpt_handoff.md (OpenAI plan-first step checklists)
├── 🔵 [GEMINI] ──► gemini_handoff.md (DeepMind hierarchical ontology)
└── ⚙️ [MACHINE] ──► project-state.json (Machine-parseable Schema 1.0.0 AST)
# ── 1. INITIALIZATION & WORKSPACE ───────────────────────────────────────────
$ continuum init [--path .] # Initialize .continuum storage & Git hooks
$ continuum scan [--path .] # Full workspace AST extraction & DAG rebuild
# ── 2. STATE INSPECTION & GRAPH ─────────────────────────────────────────────
$ continuum status [--path .] [--json] # Print verified project state & next action
$ continuum graph [--mermaid] [--stats] # Inspect DAG structure or export Mermaid
# ── 3. AI HANDOFF GENERATION ────────────────────────────────────────────────
$ continuum handoff # Auto-scan & generate Omni-Model handoffs
$ continuum handoff --model claude # Tailor specifically for Anthropic Claude
$ continuum handoff --model gpt # Tailor for OpenAI GPT-4o / Codex
$ continuum handoff --model gemini # Tailor for Google Gemini Pro
# ── 4. BROWSER COMPANION & 1-CLICK SETUP ──────────────────────────────────
$ continuum setup --browser # 1-Click Tampermonkey & Companion installer
$ continuum browser --install # Launch browser setup wizard
$ continuum launch # Auto-launch Chrome with Continuum pre-loaded
$ continuum launch --target claude # Launch directly into Claude.ai
$ continuum launch --target gemini # Launch directly into Google Gemini
$ continuum launch --target deepseek # Launch directly into DeepSeek Chat
$ continuum launch --dry-run # Inspect browser discovery without launch
$ continuum bookmarklet # Print zero-install browser bookmarklet URI
$ continuum bookmarklet --html ./card.html # Generate interactive drag-and-drop installer
# ── 5. LOCAL WEB CONTROL DASHBOARD & REST API ──────────────────────────────
$ continuum serve # Launch Local Web Dashboard & REST API
$ continuum serve --port 8765 # Launch on custom port (auto-fallback enabled)
$ continuum serve --no-browser # Start headless daemon without opening browser
$ continuum serve --watch # Enable live background filesystem observation
$ continuum serve --status # Inspect running web daemon status & auth token
$ continuum serve --stop # Gracefully terminate active web daemon
# ── 6. BACKGROUND OBSERVER DAEMON ───────────────────────────────────────────
$ continuum daemon start # Start background filesystem observer
$ continuum daemon status # Check background daemon health & cycles
$ continuum daemon run-once # Trigger a single incremental scan pass
$ continuum daemon stop # Gracefully stop the background daemonProject Continuum is certified with 450 / 450 automated tests passing (100% success) across the entire end-to-end stack:
- Core Ground-Truth Engine: Multi-language AST symbol extraction, 5-tier evidence hierarchy, dependency state graph (DAG) with topological ordering, and automated contradiction detection.
- Local Control Plane & Daemon: Zero-dependency REST API daemon on loopback, live Web Control Dashboard, constant-time session token security, and automated secret/credential masking.
- Browser Continuity Ecosystem: Cross-model companion (Userscript & native Manifest V3 WebExtension) supporting ChatGPT, Claude, Gemini, and DeepSeek with cross-tab context relay, bi-directional workspace code sync (
/api/workspace/sync), and checkpoint lineage tracking. - Conversation Context Preservation: In-session incremental accumulator, multi-platform URL isolation, streaming in-place update reconciliation, user-directed cold-start recovery, and 5-Tier Smart Digest compression engine with multi-model prompt formatting.
- Universal Resume Anywhere (v1.4.0 Track): Milestone 35 Discovery & Baseline certified (Phases 50-52); Milestone 36 Domain Models & Invariants certified (Phases 53-55); Milestone 37 Durable Storage & Migration certified (Phases 56-58); Milestone 38 Capture & Resume certified (Phases 59-62); Milestone 39 History, Diffs, Branch & Restore certified (Phases 63-66); Milestone 40 Organization and Local Search certified (Phases 67-69); Milestone 41 Artifacts, Automation and Adapters certified (Phases 70-72); Milestone 42 Retention, Privacy and Security certified across Safe Retention (Phase 73), Privacy Controls & Secret Redaction (Phase 74), and Permissions & Integrity Validation (Phase 75); Milestone 43 Export, Backup, Import and Transfer certified across Portable Export (Phase 76), Complete Backup (Phase 77), Import, Conflicts & Restore (Phase 78), and Device Transfer Guide (Phase 79); Milestone 44 Accessibility, Performance Benchmarks, and Error UX certified (Phases 80-82); Milestone 45 Regression & Release Readiness certified across Full Integration & Regression (Phase 83), Documentation & Compatibility (Phase 84), and Release Candidate Audit (Phase 85); Milestone 46 CI/CD and Final Delivery certified across GitHub Actions CI/CD (Phase 86) and Final Verification & Project Handoff (Phase 87).
$ py tests/run_all_tests.py # 516/516 Passed (100% Test Coverage across all System Modules)┌─ SECURITY & PRIVACY CONTROLS ────────────────────────────────────────────────────────────┐
│ • Zero Telemetry : 100% offline local processing with no external telemetry. │
│ • Secret Sanitization : Automatically detects and strips API keys and credentials. │
│ • Workspace Boundary : Strict path-traversal prevention locking access to workspace. │
│ • Atomic Swaps : Crash-safe state serialization preventing corrupted files. │
└──────────────────────────────────────────────────────────────────────────────────────────┘
We welcome contributions from developers and researchers building the future of cross-model AI work continuity and agent handoffs.
1. Clone Repository
git clone https://github.com/Ashish6298/CONTINUUM.gitcd CONTINUUM2. Create a Feature Branch
git checkout -b feature/ast-symbol-extractor3. Setup Virtual Environment
python -m venv .venv# On Windows:
.venv\Scripts\activate
# On macOS / Linux:
source .venv/bin/activate4. Install Development Dependencies
pip install -e ".[dev]"5. Run Automated Regression Test Suite
py tests/run_all_tests.py6. Verify Architectural Invariants
┌─ ARCHITECTURAL INVARIANTS ───────────────────────────────────────────────────────────────┐
│ • 3-State Separation : Physical workspace state is never mutated by chat claims. │
│ • Zero Telemetry : 100% offline local processing with no external network calls. │
│ • Atomic Persistence : All state writes use crash-safe atomic swaps (.tmp -> replace). │
└───────────────────────────────────────────────────────────────────────────────────────────┘
7. Commit & Open a Pull Request
git commit -m "feat(extractors): add support for rust AST parser"For complete architectural specifications, commit rules, and PR checklists, read CONTRIBUTING.md.
Project Continuum strictly enforces the Contributor Covenant v2.1 across all issues, pull requests, and community discussions.
COMMUNITY GOVERNANCE STANDARDS
├── 🌟 CORE PLEDGE ──► Harassment-free experience regardless of background
├── 🤝 COLLABORATION ──► Constructive feedback & focus on what is best for the project
└── ⚖️ ENFORCEMENT LADDER ──► Correction ──► Warning ──► Temporary Ban ──► Permanent Ban
Detailed enforcement guidelines and reporting steps are available in CODE_OF_CONDUCT.md.
Continuum is built around verifiable, non-negotiable security invariants:
STATUS INVARIANT ENFORCEMENT GUARANTEE
────────── ─────────────────────── ─────────────────────────────────────────────────────
[ENFORCED] Zero External Telemetry 100% offline execution; no network calls or telemetry
[ENFORCED] Secret Sanitization Automatic regex & entropy masking for sensitive keys
[ENFORCED] Workspace Containment Rejection of symlinks and paths escaping root
[ENFORCED] Atomic State Swaps Zero partial writes; crash-safe file serialization
Read our complete policy and disclosure process in SECURITY.md.
Project Continuum is open-source software licensed under the MIT License.
┌─ SUPPORT & COMMUNITY ────────────────────────────────────────────────────────────────────┐
│ ⭐ Star the Repo : Support open-source AI continuity on GitHub │
│ 🐛 File an Issue : Report bugs, feature requests, or AST extractor ideas │
│ 💬 Discussions : Share your multi-agent handoff setups & workflows │
│ ▲ Return to Top : Jump back to system navigation & command reference │
└──────────────────────────────────────────────────────────────────────────────────────────┘
[ ▲ BACK TO TOP ] [ ⭐ STAR REPOSITORY ] [ 🐛 REPORT ISSUE ]
Project Continuum • Open-Source AI Work Continuity & Cross-Model Agent Handoff System