ContextOS — Powered Exoskeleton for AI Coding
io.github.yubinbin32-opsPublished by GitHub account yubinbin32-opsv3.0.3Updated Nov 5, 2026
Context exoskeleton for AI development: reduce token usage and context occupancy.
Overview
Local MCP runtime that sits between an AI coding agent and a repository, keeping evidence, command logs, plans and receipts outside the main conversation to…
- What you can do
- Inspect exact source paths, line ranges and symbols, and reuse earlier evidence by result ID
- Run commands once, persist their output and exit status, and retrieve a focused section later
- Batch known steps in serial or parallel pipelines with per-step results
- Apply scoped changes or merge a worker's isolated diff with verification receipts
- Record architecture as Blocks and Chains, and persist plans, tasks, sessions and rules
- Delegate bounded work to a configured API model or an isolated CLI worker and get compact reports
- When to use it
- For long or multi-file coding sessions where the conversation fills with large file reads, test logs and repeated commands, and where work needs to resume across sessions with inspectable state. Best suited to developers already using a coding assistant who want a local execution and memory layer beneath it.
- Requirements
- Runs as a local stdio process on the desktop; Node.js 22 or later is required. The CONTEXTOS_PROJECT_ROOT environment variable must point at the project directory containing .contextos. The Micro workflow needs an API key, provider base URL and model; CLI workers need a working CLI installation, an adapter and an authenticated execution path. A desktop App and host plugins/skills are part of the setup.
Installation
In SourceWeft
- Open ContextOS — Powered Exoskeleton for AI Coding in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
ContextOS
The context exoskeleton for AI development.
Optimize the full development lifecycle. Reduce repeated token use and keep context focused.
[GitHub release] [GitHub stars] [Node.js 22+] [MIT license]
Local MCP runtime · Precise evidence · Persistent receipts · Live architecture
Give your agent an exoskeleton
[ContextOS desktop walkthrough]
ContextOS is a local development runtime between an AI coding agent and your repository. It keeps source evidence, command logs, plans, architecture, and verification receipts outside the main conversation, then returns the pieces needed for the next decision.
OS supports the entire AI development lifecycle: understand the project, plan, inspect evidence, execute, implement, verify, review, and resume. Precise reads, reusable commands, pipelines, Blocks, Chains, persistent plans, Micro, and CLI all serve the same purpose: reduce unnecessary token consumption and context occupancy while keeping development grounded in inspectable project state.
Your existing coding assistant stays in charge. OS supplies the execution and memory layer beneath it, including bounded API Micro assistance and isolated CLI implementation when a task benefits from delegation.
In a recorded real development task, the full OS + Micro + CLI workflow reduced peak main-thread context by 63.8% and main-thread cumulative raw tokens by 77.4% compared with native tools. See the task, comparison, and limits below.
Why long coding sessions get expensive
A small question often triggers a large file read. A failed test fills the conversation with logs. The agent revisits the same code, repeats a command, and spends its attention reconstructing decisions made earlier. Multi-file implementation then shares the same context window as planning and review.
The result is familiar: a crowded conversation, repeated explanations, uncertain project state, and less room for the next useful decision. A larger context window postpones the problem; development needs a way to carry this work across tools and sessions.
How OS carries the work
Evidence and logs are saved locally. Workers read task evidence in their own contexts and return compact reports. Changes pass through OS so file ownership, verification, and the project graph stay connected. A fresh session can recover the plan and receipts instead of reconstructing the entire transcript.
Capabilities and their practical effect
Micro and CLI help when the task contract is clear. A small deterministic read can use OS directly; a broad implementation belongs to a CLI worker. Delegation has overhead, so OS makes its execution and results inspectable.
Three development workflows, measured
The recorded comparison started from commit 0dd6431. Fresh host conversations and isolated worktrees received the same real feature: plan dependency add/remove/list, persistence, validation of unknown targets, duplicates, self-reference and cycles, MCP routing, and tests across domain, application, storage, and MCP layers. Historical measurement record.
What “60% less context” means here: peak input to a main-agent request fell from 234,174 to 84,681 tokens. It describes this measured task, rather than a promise for every repository or the combined tokens of every worker.
Full token usage, specified equivalent USD costs, and the OS-only control
Raw tokens are cumulative input plus output; peak context is the largest single main-agent input. Cached input is included in input, so uncached = input − cached. Reasoning tokens are included in output and are not counted or charged twice.
The specified comparison uses equivalent tokens = main raw + (Micro raw + CLI raw) / 7:
For USD, the user-specified comparison rates per million tokens are $2 for uncached input, $0.10 for cached input, and $10 for output:
base USD = (uncached input × 2 + cached input × 0.1 + output × 10) / 1,000,000
equivalent USD = main base USD + (Micro base USD + CLI base USD) / 7
These are equivalent consumption and costs under the specified model, not actual provider invoices or verified provider rates. The assistant divisor of 7 is a chosen comparison assumption. All main sessions reported the deepseek-v4.1-flash alias with max reasoning effort and a custom provider; Micro C/D retained the same session lastModel, and D CLI reported the same alias/custom provider. This does not independently verify the underlying backend model.
Main usage is deduplicated by provider response ID and matches terminal cumulative totals. C Micro has 2 receipts and provider usage for all 26/26 started requests. D CLI has 51 unique cumulative states whose last-usage sum matches its terminal total. † D Micro has 5 receipts, 129 started requests and 128 usage-bearing responses. One continuation timeout request has unknown usage. D totals and the 51.3% cost reduction are observed subtotals; the missing request is not assigned zero. Original Micro reasoning fields are unavailable and remain unknown.
The full workflow used more observed total raw tokens than native tools while reducing peak main context. OS-only reached 184,507 peak tokens (−21.2%) and lower equivalent USD than OS + Micro in this run. This is one feature's historical single-run comparison; results vary with task, model, caching and delegation.
Inspect the frozen evidence and methodology, original usage fields and coverage, role costs CSV, and four-arm totals CSV. Recompute and check the published file hashes with:
See your project in the App
The desktop App projects the same OS state that agents use: Blocks, Chains, plans, checkpoints, rules, and knowledge. Its white canvas, restrained color, and precise connections make a large project readable.
[Live Block and Chain architecture canvas]
Read the whole system at a glance. Follow a Chain through its Blocks, inspect the selected capability, and see implementation and verification progress alongside the graph.
Trace a feature and inspect its evidence
[A feature path across integration, UI, and testing Blocks]
Follow impact across modules. A highlighted Chain connects integration, packaging, and verification work.
[A passed checkpoint with its receipt reference]
See the evidence behind completion. Checkpoints expose their status and receipt references.
Read project knowledge and synchronize your tools
[Project knowledge and rules navigation]
Keep project knowledge close. Open repository documentation and rules from the project sidebar.
[Repository README in the desktop reader]
Read documentation inside the App. The reader opens repository content alongside the project; performance figures follow the reproducible evidence below.
[Desktop settings and AI editor synchronization]
Manage your development environment. Settings bring preferences and host integration into the App. Configure shared models and reasoning levels, let each role inherit them with Use Global, and synchronize available models and effort options for Micro and CLI adapters.
The settings image above shows an earlier accepted layout.
[MCP and skill integration in an AI host]
Use OS from your coding assistant. The host loads the MCP runtime and matching skill so the agent can operate on project state.
Some gallery images were captured from earlier builds and retain the former mdflow name or earlier version labels. They demonstrate the workflow; follow the installer for the current runtime and configuration.
Install with one prompt
Paste this into your AI coding assistant:
读取 (https://github.com/yubinbin32-ops/ContextOS/blob/main/setup.md) ，为我安装OS
The agent reads setup.md, installs OS and matching host plugins/skills, registers your repository, configures API Micro and your CLI, and verifies the result with real tool calls. It handles dependency checks, adapter creation, plugin setup, and diagnosis for you.
You do not need to download and configure a Release package by hand. The setup guide is written for the installing agent, including diagnosis, adapter configuration, plugin installation, and acceptance checks.
Micro is required
Micro is the small assistant for routine work, and its API connection is required for the OS workflow. Prepare an API key, provider base URL, and model. A main-agent subscription or CLI login alone does not configure API Micro.
Recommended options:
- Command Code GOAT: includes Provider API access. Create a key in its console; let the agent use the provider's current endpoint and exact model ID.
- OpenCode Go: provides a subscription API key and available coding models. Have the agent check the current model list and API configuration.
- Your own compatible API: use a provider you already trust, including the DeepSeek API.
For bounded Micro tasks, we recommend DeepSeek V4.1 Flash with medium reasoning where the provider supports it. The official DeepSeek model ID is deepseek-flash; gateways can use different IDs. The installer must verify model availability and map the provider's reasoning setting instead of assuming every API accepts the same parameters.
Keep the key in the local credential/configuration path established by the installer. Do not paste it into repository documentation or tracked source.
CLI setup is completed by the agent
CLI workers require a working CLI installation, an adapter, the matching ContextOS plugin/skills, and a verified authenticated execution path. Tell the agent which CLI you use; it should consult that CLI's official documentation, write the adapter, configure OS, and run a real probe and isolated implementation check.
A login, browser authorization, or operating-system permission may require your action. The agent should identify that exact step, continue the remaining setup, and verify readiness after you complete it. A discovered binary or saved adapter alone is not a successful installation.
Node.js 22 or later is required. After a plugin/runtime update, reload the host's MCP process as directed by setup. Keep the App, plugin, skills, and runtime on matching versions.
Daily use, in ordinary language
The main agent keeps the acceptance criteria and final review. Micro and CLI take bounded assignments; OS retains the evidence and progress between them.
What's new in 3.0.0
The 3.0 line, prepared from 4706c38, restructures ContextOS into an exoskeleton for the full AI development lifecycle:
- Precise evidence and reusable commands keep source inspection and execution results focused and recoverable.
- Pipelines and verified changes connect batched execution, scoped edits, and reviewable results.
- Architecture and continuity keep plans, tasks, sessions, Blocks, Chains, and receipts available across conversations and in the desktop App.
- Task-appropriate delegation adds bounded API Micro assistance and isolated CLI implementation to the same OS lifecycle.
- AI-led installation makes provider configuration, host plugins, CLI adapters, diagnosis, and real acceptance checks part of setup.
See the 3.0 release notes, installation guide, and release history.
If ContextOS helps your agent stay focused, give the project a star. Reproducible tasks and issue reports help us improve the next release.
Source: README.md at commit 51b093a
Tools
0Version history
11- v3.0.3LatestOct 7, 2026
- v3.0.2Oct 5, 2026
- v2.7.1Sep 30, 2026
- v2.7.0Sep 29, 2026
- v2.5.5Sep 23, 2026
- v2.5.2Sep 21, 2026
- v2.5.1Sep 21, 2026
- v2.2.2Sep 18, 2026
- v2.2.1Sep 17, 2026
- v2.1.0Sep 17, 2026
- v2.0.3Sep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts