█▀▀ █▀█ █▄ █ ▀█▀ █ █▄ █ █ █ █ █ █▀▄▀█
█▄▄ █▄█ █ ▀█ █ █ █ ▀█ █▄█ █▄█ █ ▀ █
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 │ ├── ❯ 🚀 What's New in v1.2.0 (Browser Companion & Web Suite) │ ├── ❯ 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 ├── ❯ Roadmap to v1.2.0 (All 48 Phases) ├── ❯ 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.2.0 expands Continuum from an automated CLI AST extraction engine into a complete Cross-Model AI Chat & Browser Continuity Ecosystem. It bridges the gap between web-based AI chats (ChatGPT, Claude.ai, Gemini, DeepSeek) and local terminal IDE coding agents (Claude Code, Cursor, Codex, Antigravity).
| v1.2.0 Feature | Technical Architecture & Capabilities |
|---|---|
| 🧩 1-Click Browser Companion |
Tampermonkey / Violentmonkey userscript (browser/continuum.user.js) and native Manifest V3 WebExtension (browser/extension/) running directly on ChatGPT, Claude.ai, Google AI Studio, Gemini, and DeepSeek.
|
| 🖥️ Local Web Control Dashboard |
Embedded, zero-dependency HTTP server (server/daemon.py) running at http://127.0.0.1:8765 with automatic port fallback negotiation.
|
| 🚀 Native Browser Launcher |
continuum launch --target <model> automatically discovers Chrome, Brave, and Edge binaries across Windows, macOS, and Linux, launching Chromium with the Continuum companion extension pre-loaded.
|
| 🔖 Zero-Install 1-Click Bookmarklet |
continuum bookmarklet compiles a standalone, minified javascript: URI installer for enterprise or restricted environments where browser extensions cannot be installed.
|
| 🔄 Bi-Directional Code Sync Engine |
POST /api/workspace/sync enables the browser companion to push generated code snippets directly back into workspace files with atomic write safety, automatic backups (.bak), and path traversal guards.
|
| 📜 Multi-Turn Relay & Checkpoints |
/api/checkpoints manages multi-turn handoff lineage, capturing branching trails across 3+ AI models (e.g. ChatGPT ➔ Claude ➔ DeepSeek ➔ Gemini) with rollback and resume points.
|
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.
─────────────────────────────────────────────────────────────────────────────
v1.2.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 v1.2.0 is fully certified with 197 / 197 automated tests passing (100%) across all core CLI and Browser Companion roadmap phases:
- Milestones 1–8 (Phases 0–23): Core Engine, AST Extractors, DAG State Graph, Contradiction Ledger, and Omni-Model CLI Handoffs.
- Milestones 24–30 (Phases 25–37): Web Control Dashboard, REST API Daemon, Secret Sanitizer, and Security CORS Guards.
- Milestones 31–34 (Phases 38–48): Browser-to-Browser Cross-Model Handoff Companion, Native Manifest V3 WebExtension (
browser/extension/), CLI Browser Launcher (continuum launch), Zero-Install Bookmarklet (continuum bookmarklet), Bi-Directional Code Sync (/api/workspace/sync), Multi-Turn Handoff History & Checkpointing (HandoffCheckpointManager,/api/checkpoints), Automated Browser Companion Test Suite (tests/test_browser_companion.py), CLI Launcher Test Suite (tests/test_cli_launcher.py), and General Availability Release Validation (tests/test_ga_validation.py).
Detailed engineering reports and verification logs are available in docs/reports/.
$ py tests/run_all_tests.py # 197/197 Passed (100% Test Coverage across all Phases)┌─ 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 24-Phase 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