A High-Precision Powered Exoskeleton for AI Coding

Auto-governing context via MCP, reducing context window waste by 90%+ in practice.

Stopping context window explosion and hallucination in large codebases: surgical AST read/write instead of dumping whole files, out-of-context command receipts, and an intuitive Metro Map architecture.

Download macOS Desktop App · Start in 30 seconds · 中文文档

ContextOS acts as a high-precision powered exoskeleton for AI coding assistants: In traditional workflows with large repositories, an AI agent is forced to haul massive raw files, noisy build dumps, and repetitive documentation in its prompt. It quickly runs out of breath — the context window explodes, hallucinations multiply, and previous design decisions are forgotten.

With ContextOS, the AI sheds the deadweight and lets the MCP protocol auto-govern context:

1. Exoskeleton-Powered Precision: Compiler-grade AST tools surgically inspect and edit only the relevant symbols and syntax blocks, eliminating whole-file dumps;
2. Out-of-Context Isolation: Terminal logs are safely captured to a sandboxed disk store, returning compact diagnostic receipts to strip 98%+ of terminal noise;
3. Unified Neural Metro Map: Architectural memory and the C-D-C-S task lifecycle are synchronized in a visual subway map, giving the AI immediate full-picture clarity.

In real-world multi-step tasks, ContextOS reduces redundant context consumption by over 90%, eliminating context explosion and memory loss across long-running sessions.

Blocks describe real, verified code modules (zero ghost blocks allowed). Chains represent horizontal subway rails, and typed Links connect transfer stations orthogonally. The agent understands the big picture without touching the code.

Work flows strictly through Create → Develop → Check → Sync. Tasks carry an explicit context slice, intermediate development notes, and sandboxed test checks, completing with an atomic sync that enforces a 100% workspace code coverage gate.

run_command strips ANSI noise, redacts secrets, saves full raw logs into .contextos/logs/, and returns a compact receipt with critical error diagnostics, reducing terminal noise by over 98%.

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.

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.

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.

ContextOS offers three flexible onboarding options for any workflow:

graph TD
    User([Choose Your Setup Route]) --> ChoiceA[Option A: Download Desktop App]
    User --> ChoiceB[Option B: AI Auto-Setup via Prompt]
    User --> ChoiceC[Option C: Standalone mjs Plugin]
    
    ChoiceA --> FlowA[Plug & Play · Visual Metro Map · One-Click Editor Injection]
    ChoiceB --> FlowB[Zero Effort · AI Detects Environment & Configures MCP]
    ChoiceC --> FlowC[Geek & Headless · Linux/Windows/Containers · Direct stdio/npx]

Download the package matching your environment from GitHub Releases:

1. Unzip the downloaded archive and drag ContextOS.app into /Applications.
2. Launch ContextOS, open Settings (gear icon or Cmd+,), select your detected AI editor (Cursor / Claude Desktop / Antigravity / OpenCode / Codex), and click Install / Sync Plugin.
3. The App injects the ContextOS MCP configuration and unique Skills directly into your editors. Once configured, you can close the desktop App; it does NOT need to stay running.
4. In your AI coding chat, simply activate ContextOS:

   "Write this proposal into ContextOS and start execution" or "Inspect ContextOS and resume development"

If you are already in an AI coding assistant (Cursor / Codex / Claude Code / Windsurf / Antigravity), let the AI configure everything automatically:

Copy and paste this instruction into your AI coding assistant:
"Please read https://github.com/yubinbin32-ops/ContextOS/blob/main/AI_SETUP.md, detect my system environment, and configure ContextOS for me."

1. System & Client Inspection: If on macOS, asks if you want the native Desktop App (ContextOS.app) and deploys it automatically.
2. Runtime Verification: Checks for Node.js 22+ (or uses the runtime bundled with ContextOS.app).
3. Targeted Precision Injection: Asks which editors you use (Cursor / Codex / Claude Desktop, etc.) and injects only the selected platforms, eliminating duplicate skill noise.
4. Demand-Driven Collaboration Mode: Asks if you need solo local development or team collaboration, configuring local SQLite or Cloudflare D1 accordingly.
5. Project Initialization: Initializes the current project and verifies tools.

npx -y github:yubinbin32-ops/ContextOS

Download the compiled single-file bundle from the repository: plugins/contextos/server/contextos-mcp.mjs.

Add standard stdio MCP configuration to your editor (mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "contextos": {
      "command": "node",
      "args": ["/absolute/path/to/plugins/contextos/server/contextos-mcp.mjs"]
    }
  }
}

ContextOS treats the local workspace project directory as the absolute source of truth (code reads, AST edits, test runs, and logs always run locally):

• Local Storage Mode: Designed for solo development. Architecture data is stored in the project's .contextos/state.sqlite. 100% offline, private, and zero network latency.
• Cloud Collaboration Mode: Designed for team collaboration. Connects to a serverless Cloud Hub (Cloudflare D1 edge database) to synchronize architectural topology and progress across teammates and devices.
  • Multi-Project Strict Isolation: Cloud Hub partitions entities by projectId. A single Cloudflare Worker backs multiple independent repositories cleanly.
• Lossless Two-Way Switching: Switch storage modes anytime by prompting your AI:
  • "Switch current project to cloud collaboration mode" ➔ Local SQLite graph is pushed to Cloud D1.
  • "Switch current project back to offline local mode" ➔ Cloud snapshot is synced back to local SQLite for offline development.

The measurements below were verified on the self-adopted ContextOS V2 repository (18 Blocks, 3 Chains, 18 Links, 49 files, 100% coverage).

Run the benchmarks locally:

node scripts/benchmark.mjs
node scripts/practical-test.mjs
node scripts/e2e-project-lifecycle.mjs
node scripts/comprehensive-dev-eval.mjs

git clone https://github.com/yubinbin32-ops/ContextOS.git
cd ContextOS
npm ci
npm test
npm run plugin:verify
npm run desktop:build       # macOS + Swift/Xcode

The versioned .contextos/graph.json is the project's portable graph projection.

Contributing · Security · MIT License