continuum-toolkit 1.4.0

  █▀▀ █▀█ █▄ █ ▀█▀ █ █▄ █ █ █ █ █ █▀▄▀█
  █▄▄ █▄█ █ ▀█  █  █ █ ▀█ █▄█ █▄█ █ ▀ █

AI Work Continuity & Cross-Model Agent Handoff System

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

🧭 Navigation

# 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

💡 What is Continuum?

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.

🌟 What's New in v1.4.0 (Latest Release): Universal Work Continuity & Resume Anywhere

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.

⚔️ Why Continuum over Chat Summaries?

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 ✅

📊 Capability Benchmark Matrix

🔬 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)

⚡ Quick Start Guide

1. Installation

# Install via PyPI
pip install continuum-toolkit

# Or install from source
git clone https://github.com/Ashish6298/CONTINUUM.git
cd CONTINUUM
pip install -e .

2. Choose Your Workflow

                 █▀▀ █▀█ █▄ █ ▀█▀ █ █▄ █ █ █ █ █ █▀▄▀█
                 █▄▄ █▄█ █ ▀█  █  █ █ ▀█ █▄█ █▄█ █ ▀ █

             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   

3. Web Browser Workflow (1-Click Companion Setup)

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:8765 in 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.

4. Terminal & IDE Coding Agent Workflow (Instant Handoff)

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."

🏛️ Three-State Separation Architecture

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)                    │
  └──────────────────────────────────────────────────────────────────────────────────────────────────┘

⚖️ 5-Tier Evidence Hierarchy Matrix

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.           │
└─────────────────────────────────────────────────────────────────────────────────┘

🕸️ Canonical State Graph (DAG)

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.                         │
└─────────────────────────────────────────────────────────────────────────────────────────┘

🤖 Smart Omni-Model Handoff Adapters

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)

💻 Complete CLI Command Reference

# ── 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 daemon

🗺️ System Architecture & Verification

Project 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).

🧪 Testing & Enterprise Security

$ 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.      │
└──────────────────────────────────────────────────────────────────────────────────────────┘

🤝 Contributing

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.git

cd CONTINUUM

2. Create a Feature Branch

git checkout -b feature/ast-symbol-extractor

3. Setup Virtual Environment

python -m venv .venv

# On Windows:
.venv\Scripts\activate

# On macOS / Linux:
source .venv/bin/activate

4. Install Development Dependencies

pip install -e ".[dev]"

5. Run Automated Regression Test Suite

py tests/run_all_tests.py

6. 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.

📜 Code of Conduct

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.

🛡️ Security & Privacy

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.

⚖️ License

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                   │
└──────────────────────────────────────────────────────────────────────────────────────────┘