ContextOS — Context Operating System for AI Coding Agents

A Deterministic Context Operating System & MCP Execution Layer for AI Coding Agents

Mitigating context window saturation and attention drift in LLM-driven engineering through syntax-directed AST slicing, out-of-band execution isolation, in-situ test diagnostics, topological metro maps, and out-of-band Micro dual-brain subagents.

Current Version: 2.7.0 · Native multi-host integration · Official macOS & Windows Desktop Apps · Micro Dual-Brain

Download Desktop App · Quick Setup Guide · AI Auto-Setup Specification · 中文文档

ContextOS Interactive Workflow Demo

1. What is ContextOS?

ContextOS is not a collection of ad-hoc helper scripts—it is an operating system for LLM context windows (Context Operating System) embedded into the AI coding agent's execution lifecycle.

In conventional AI programming, an LLM acts like a "bare-metal program without an OS", interacting directly with terminals and dumping raw files into prompt history. This inevitably leads to context explosions, catastrophic attention drift, and session amnesia.

ContextOS bridges the AI agent and the codebase via the Model Context Protocol (MCP), providing a deterministic system orchestration layer:

• Materializes the codebase into a Metro Map: Strongly typed Block-Chain-Link architecture;
• Transforms raw file reads into surgical AST slices: Extracts only targeted method bodies and interface outlines;
• Isolates terminal execution out-of-band: Build logs and test traces run in a private sandbox;
• Delivers in-situ failure diagnostics: Embeds test execution and assertion diff parsing directly into code mutation steps;
• Deploys a Micro Dual-Brain Subagent: Triages tens of thousands of characters of verbose compiler traces out-of-band, keeping the host conversation focused.

2. What Problems Does It Solve?

3. How We Do It (Core Architecture & Mechanisms)

graph LR
    User[Agent Intent] --> Explore[1. explore: Topological Discovery]
    Explore -->|Provisions Slots S1, S2 + AST Slices| Inspect[2. inspect: Surgical Ingestion]
    Inspect -->|Single-Turn Ingestion| Change[3. change + verify: In-Situ Mutation]
    Change -->|On Failure: In-Situ Diagnostic Diff / autoRevert| Change
    Change -->|Tests Pass| Ship[4. ship: Topological Closure]
    Ship --> Blackboard[Update 300-Byte Blackboard & Graph]
    
    subgraph Out-of-Band Sandbox
        Micro[Micro Subagent<br>Log De-noising / Contract Distillation]
        Desktop[Desktop App<br>Live Metro Map Visualization]
    end
    Change -.->|Logs > 2000 Chars| Micro
    Ship -.-> Desktop

1. Architecture as a Metro Map

Blocks represent stable semantic files or AST symbols, Chains represent horizontal business subway lines, and typed Links represent cross-subsystem transfer stations. The official desktop app (macOS & Windows) provides live interactive subway maps.

2. Action Slots & In-Situ Diagnostics

• Action Slots: explore analyzes intent and outputs actionable slots [S1], [S2]. The AI selects a slot and passes change({ slot: "S1", append: "..." }) with zero parameter alignment friction.
• In-Situ Verify: change can embed verify: "npm test". If tests fail, extractDiagnosticBlocks automatically parses assertion diffs (+ actual - expected) and file:line:col stack frames directly into the response. If needed, autoRevert: true rolls back disk modifications in milliseconds.

3. Out-of-Band Execution & Log Sanitization

Commands execute through an isolated gateway that strips ANSI noise and redacts secrets. Full logs are stored in .contextos/logs/, returning compact signed receipts to the LLM, reducing terminal context noise by >98%.

4. 300-Byte Persistent Blackboard

Session state is continuously persisted to a minimal ~300-byte (~65 tokens) blackboard (.contextos/blackboard.md). After /clear, calling explore resumes complete context in ~150 tokens.

5. Micro Dual-Brain Subagent

Heavy compiler traces, massive test outputs, and contract distillation are delegated out-of-band to Micro. Compatible with any OpenAI-format endpoint (OpenCode Go, DeepSeek, or local Ollama), Micro digests bulk text in a background sandbox and returns a concise summary receipt.

4. Performance & Tool-by-Tool ROI (Real-World Benchmark)

Tool-by-Tool Improvement Breakdown

Objective ROI Boundary & Task Complexity Analysis (A/B Test Reality)

Different task complexities yield drastically different returns on context operating systems. We present real-world data transparently:

[Task Complexity vs ContextOS Token ROI]

Token
Savings %
  ▲
70%│                                     ● Complex Long-Horizon Tasks (50%~75% Savings)
  │                              ● 
  │                      ● Medium Multi-File Tasks (20%~40% Savings)
 0%├─────────────────────┬───────────────────────────────► Task Complexity
   │ Trivial Edits (Negative ROI) ●
-80%│

1. ⚠️ Trivial Tasks (Single-file tweak, 1-line bugfix, short Q&A):
   • Empirical Return: NEGATIVE ROI (-50% ~ -200%)!
   • Root Cause: Maintaining the Metro map, slot calculations, and blackboard synchronization incurs ~2,000–4,000 tokens of fixed protocol metadata. For a 1-line edit (which takes ~500 tokens with native tools), running the full OS ceremony is counterproductive.
   • Best Practice: For simple 1-line edits, use native editing tools or a single direct change without full explore/ship ceremonies!
2. ✅ Medium Tasks (3–6 turns, 2–4 files, accompanied by unit tests):
   • Empirical Return: MODERATE POSITIVE ROI (20% ~ 40% token savings). In-situ verification and parallel AST batching eliminate waiting roundtrips.
3. 🚀 Complex Long-Horizon Tasks (10+ turns, deep test debugging, large refactor, multi-day handoffs):
   • Empirical Return: MASSIVE POSITIVE ROI (50% ~ 75% total token savings, >50% turn reduction). Completely eliminates log explosions and session amnesia.

Running Your Own A/B Test

Use the built-in telemetry audit capability to compare real token consumption between sessions:

contextos({
  action: "ops",
  args: {
    capability: "telemetry",
    action: "audit",
    args: { sessionId: "current-session", baselineSessionId: "baseline-session" }
  },
  projectRoot: process.cwd()
})

5. Quick Start & Setup Options

ContextOS provides two straightforward onboarding routes:

graph TD
    User([Choose Setup Route]) --> ChoiceA[Option A: Official Desktop App]
    User --> ChoiceB[Option B: AI Auto-Setup via Prompt]
    
    ChoiceA --> FlowA[Plug & Play · Visual Metro Map · One-Click Editor Sync]
    ChoiceB --> FlowB[Zero Effort · AI Configures MCP & Verifies Environment]

Option A: Desktop App (macOS & Windows · Plug & Play · Recommended)

Download the package matching your environment from GitHub Releases:

Setup Steps:

1. Launch ContextOS:
   • macOS: Unzip archive and drag ContextOS.app into /Applications.
   • Windows: Run the installer .exe or extract the portable .zip.
2. One-Click Sync:
   • Open ContextOS, click Settings (gear icon), select your AI editor (Cursor / Codex / Claude Desktop / Antigravity / OpenCode), and click Install / Sync Plugin.
3. Done:
   • Once configured, you can close the Desktop App; it does not need to stay running in the background.
4. macOS Gatekeeper Warning ("Unidentified Developer" or "Cannot be opened")?
   • As an open-source tool without paid Apple notarization, Gatekeeper blocks first launch by default. Allow it once:
     • Method 1 (Recommended): Open System Settings ➔ Privacy & Security, scroll down to Security, and click Open Anyway next to "ContextOS.app was blocked".
     • Method 2 (Control-Click): In Finder, open /Applications, hold Control and click (or right-click) ContextOS.app, and select Open.

Option B: AI Auto-Setup via Prompt (Zero Effort)

If you are already in an AI coding assistant (Codex / Claude Code / Cursor / Antigravity / OpenCode):

Copy and paste this instruction into your AI coding assistant:
"Please read AI_SETUP.md, detect my system environment, and configure ContextOS for me."

The AI will follow AI_SETUP.md automatically:

1. Recommends Desktop App or MCP injection based on OS;
2. Injects MCP configuration and unique Skills without duplicate clutter;
3. Recommends local storage mode for rock-solid stability;
4. Inquires about Micro dual-brain setup;
5. Runs doctor verification and outputs a readiness card.

6. Storage Modes & Recommendations

ContextOS treats the local workspace project directory as the absolute source of truth:

• Local Storage Mode (Strongly Recommended ⭐⭐⭐⭐⭐):
  • Architecture data resides in .contextos/state.sqlite;
  • 100% offline, zero network latency, complete privacy;
  • The standard choice for all solo development.
• Experimental Cloud Collaboration Mode (Public Beta ⚠️):
  • Synchronizes the graph across teammates and devices using Cloudflare D1 edge database;
  • Current status: Under active development and testing. Recommend local mode unless team real-time sync is strictly necessary.
• Lossless Two-Way Switching:
  • Say to your AI: "Switch current project to cloud collaboration" ➔ Local SQLite graph is pushed to Cloud D1;
  • Say to your AI: "Switch current project back to offline local mode" ➔ Cloud snapshot is synced back to local SQLite.

7. Recent Changelog

v2.6.x (Latest Release)

• Lean MCP Surface: Unified the primary interface into a single compact contextos MCP transport, reducing prompt definition token footprint;
• In-Situ Test Failure Diagnostics: Embedded extractDiagnosticBlocks into change, extracting TAP/Jest assertion diffs and stack frames directly into failure responses;
• Official Windows Native Desktop App: Released official Windows 10/11 installers and portable packages with 1:1 Metro map parity;
• Micro Dual-Brain Subagent: Added OpenAI-compatible background subagent integration (OpenCode Go / DeepSeek / Ollama) with concurrent pipeline preloading and out-of-band log de-noising;
• Doctor Diagnostic Engine: Added system doctor command to inspect Node runtime, storage mode, editor configurations, and Cloud connectivity;
• Lossless Storage Migration: Added atomic two-way switching between local SQLite and cloud Cloudflare D1.

8. For Contributors

git clone https://github.com/yubinbin32-ops/ContextOS.git
cd ContextOS
npm ci
npm test
npm run plugin:verify      # plugin specification and smoke test
npm run dist:smoke         # distribution layout validation
npm run desktop:build      # build desktop app (macOS)

Contributing · Security · MIT License