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.

Download macOS App · Quick Setup Guide · 中文文档

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

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:

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: