ContextOS β Context Operating System for AI Coding Agents
A Deterministic Context Operating System via Model Context Protocol (MCP)
Mitigating context window saturation and attention drift in agentic software engineering through syntax-directed AST manipulation, out-of-band execution isolation, in-situ verification, and topological priority scheduling.
[](https://github.com/yubinbin32-ops/ContextOS/stargazers)
[](https://www.npmjs.com/package/contextos)
[](https://nodejs.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
[**Download macOS App**](https://github.com/yubinbin32-ops/ContextOS/releases/latest) Β· [**Quick Setup Guide**](#start-in-30-seconds-ai-auto-setup) Β· [**δΈζζζ‘£**](https://github.com/yubinbin32-ops/Mdflow-Canvas/blob/HEAD/README_zh.md)
---
---
## Background and System Motivation (Context Saturation & Attention Drift)
In complex software repositories, autonomous AI coding agents face a fundamental systems bottleneck: **rapid context window saturation and attention drift**. Under conventional agent workflows, assistants rely on indiscriminate whole-file dumping, raw build/test stdout feedback, and conversational trial-and-error. This introduces three systemic failures:
1. **Attention Budget Dilution & Hallucination**: Large volumes of raw build dumps and irrelevant source lines displace critical architectural invariants and type signatures in the prompt;
2. **Exponential Cost of Fault Investigation**: Truncated test outputs force the agent into recursive log-retrieval turns, compounding cumulative token consumption quadratically;
3. **Architectural Blindness & Session Amnesia**: Without a verifiable global symbol graph, clearing the context (`/clear`) or transferring tasks across subagents results in complete state degradation.
**ContextOS addresses this as a Context Operating System implemented over the Model Context Protocol (MCP)**:
| Subsystem | Architectural Mechanism | Empirical Impact |
|---|---|---|
| **Syntax-Directed Access** | Tree-sitter multi-language AST engine extracting surgical symbol outlines and method slices | Eliminates whole-file dumps; reduces code ingestion volume by >80% |
| **Out-of-Band Execution** | Process execution and raw logs isolated outside the LLM context; returns signed receipts and diagnostic frames | Strips >98% of terminal noise; zero-turn error inspection |
| **Metro Map Topology** | Materializes files, symbols, and dependencies into a strongly typed Block-Chain-Link graph | Provides a deterministic structural backbone, preventing cross-module hallucinations |
| **Persistent State Blackboard** | Minimal 300-byte incremental snapshot decoupling active state from chat history | Resumes full working context in ~150 tokens on cold boot |
> Across real-world multi-step benchmarks, ContextOS reduces redundant context consumption by over 90%, stabilizing attention and ensuring long-horizon development convergence.
---
## What changes in daily development?
### 1. Architecture becomes a Metro Map
Blocks bind to real files, AST symbols, or directory trees (zero ghost blocks allowed). Dependency and resource directories use one bounded tree anchor instead of per-file bookkeeping; Chains represent horizontal subway rails, and typed Links connect transfer stations orthogonally.
### 2. Intent-Level 2-Turn Loop, Action Slots & In-Situ Diagnostics
- **Action Slots & Zero-Alignment Friction**: `explore` automatically provisions actionable target slots `[S1]`, `[S2]`. The AI doesn't need to guess line numbers or fiddle with verbatim target strings; it simply selects a slot and passes `change({ slot: "S1", append: "..." })` or replaces a symbol, completely eliminating parameter alignment failures.
- **In-Situ Verification & Instant Diagnostic Frames Extraction**:
- The `change` step can embed the verification command directly (`verify: "npm test"`), atomically performing code patching, test execution, and receipt generation in a **single turn**.
- **Eliminating Extra Log Rounds**: When a test fails in conventional workflows, truncated terminal output forces the AI to start 2β3 extra conversation turns just to inspect logs, wasting 20,000β40,000 tokens per incident. ContextOS features a built-in diagnostic extraction engine (`extractDiagnosticBlocks`) that parses TAP, Mocha, Jest, and SyntaxError frames directly, inlining test names, `+ actual - expected` assertion diffs, and exact `file:line:col` stacks into the `change` failure response. The AI sees the exact issue in the same turn with **0 extra log-fetching rounds**.
- **Auto-Revert**: If tests fail, `autoRevert: true` instantly restores disk modifications in milliseconds, collapsing the traditional 6β9 round-trip debug cycle into an ultra-fast **2-turn loop** (`explore` β `change` with in-situ `verify` β `ship`).
- **Parallel Batching Over Serial Turns**:
- Conventional AI tools encourage conversational, single-file serial editing that balloons context quadratically across turns.
- ContextOS natively supports multi-concurrency: batch multi-file modifications in `edits: [...]` arrays and inspect multiple microservices in parallel via `inspect({ paths: [...] })`, cutting round-trip latency by over 60%.
- **Topological Retention Priority**:
- Uses a priority-weighted context budgeting algorithm: `next` (0) β `slots` (1) β `where` (2) β `now` (3) β `slices` (4). In large repos, local code previews are clipped first, **guaranteeing that the system architecture map and action slots are never truncated**.
- **Lightweight Real-Time Blackboard & Instant Hydration (`.contextos/blackboard.md`)**:
- The active session state is continuously persisted to a minimal **300-byte (~65 tokens)** blackboard. Developers or agents can `/clear` the chat at any time or hand off tasks across subagents; calling `explore` resumes full context in ~**150 tokens**, preventing multi-turn context inflation.
### 3. Commands run out-of-context
The command gateway behind `verify` and in-situ `change.verify` strips ANSI noise, redacts secrets, saves the full sanitized log into `.contextos/logs/`, and returns a compact receipt with critical diagnostics, reducing terminal noise by over 98%.
### 4. Code tools operate surgically with deep slicing (`inspect`)
Multi-language AST engines (compiler-grade parsing for JS/TS/JSX/TSX, Python, Swift, Java, Kotlin, C/C++, C#, Go, Rust, PHP, Ruby) allow VS Code-style symbol search, outline inspection, and surgical reading/editing with automatic symbol re-anchoring. The first-class `inspect` tool allows on-demand semantic slicing. When answering pure inquiry/comprehension queries ("where is X", "who calls Y"), the OS automatically omits unneeded edit slots and slices, cutting query context by another 50%.
### 5. Unified Knowledge & Architectural Decisions
Proposals, audits, architectural decisions, and rules live as OS Documents. `README.md` and `README_zh.md` appear read-only in the App Knowledge view with images and links intact.
### 6. Verification with Evidence
Every `verify` run produces a signed receipt. Checkpoints track pass/fail status per task, giving AI and humans a shared source of truth for what has actually been proven to work.
### 7. Long-running processes are monitored live
Dev servers, watchers, and background workers are managed by the Process Host and displayed in the Desktop App's bottom-left sidebar with live PID and port tracking.
---
## Quick Start & Setup Options
ContextOS offers two straightforward onboarding routes for effortless setup:
```mermaid
graph TD
User([Choose Your Setup Route]) --> ChoiceA[Option A: Download Desktop App]
User --> ChoiceB[Option B: AI Auto-Setup via Prompt]
ChoiceA --> FlowA[Plug & Play Β· Visual Metro Map Β· One-Click Editor Injection]
ChoiceB --> FlowB[Zero Effort Β· AI Detects Environment & Configures MCP]
```
---
### Option A: Desktop App (macOS & Windows Β· Plug & Play Β· Recommended)
Download the package matching your environment from [GitHub Releases](https://github.com/yubinbin32-ops/ContextOS/releases/latest):
| Platform | Package | File | Size | Node.js Requirement | Best For |
|---|---|---|---|---|---|
| **Windows** | **NSIS Setup** *(Recommended)* | `ContextOS_