mdflow — Context OS for AI Coding Agents

ContextOS The context exoskeleton for AI development. Optimize the full development lifecycle. Reduce repeated token use and keep context focused.

Local MCP runtime · Precise evidence · Persistent receipts · Live architecture

中文 · Install with AI · Measured results · Desktop App

Give your agent an exoskeleton

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

You → Main agent: plan, scope, architecture, review

│ └─ ContextOS: evidence, commands, changes, persistent state ├─ API Micro: bounded discovery, summaries, small checks ├─ CLI worker: isolated implementation → report → integration └─ Desktop App: architecture, plans, checkpoints, settings

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:

python3 docs/benchmarks/plan-dependencies/recalculate.py --check

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.

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

Follow impact across modules. A highlighted Chain connects integration, packaging, and verification work.

![A passed checkpoint with its receipt r