Build AI coding assistants that stay focused with a lightweight context layer

AI-powered coding assistants like GitHub Copilot and Anthropic’s Claude promise to accelerate development, but they frequently stumble over an overlooked challenge: context overload. When developers paste a task like "add logging to the payment service," these tools often ingest the entire repository—or risk missing critical dependencies. That’s why ContextOS emerged as a lightweight alternative.

The tool acts as a local middleware between your codebase and AI agents, parsing project structure and filtering files based on relevance before sending anything to the LLM. Instead of dumping gigabytes of unrelated code into the prompt, it curates a targeted context pack containing only the modules, functions, and classes your task requires. Developers can install it via pip and run scans without connecting to external servers, ensuring privacy and reducing token waste.

How ContextOS reduces context bloat before it happens

Developers have long faced a trade-off when using AI assistants. Either they:

• Overload the context window with the entire repository, wasting tokens on irrelevant files, or
• Manually curate a subset of files, risking missed dependencies that break functionality.

ContextOS automates this process by analyzing five distinct signals to rank every file in your project. These signals include:

• Keyword matching – files whose names or contents contain task-related terms.
• Import graph centrality – modules that other files frequently import, indicating core logic.
• AST symbol overlap – functions, classes, and variables referenced in the task, not just raw text matches.
• Git churn score – recently modified files that likely represent active development areas.
• Secret penalty – automatic exclusion of credential files to prevent accidental exposure.

The system then generates a prioritized list, ranks files by relevance, and exports a compact context pack. In one internal test, scanning a 12-file subset for a rate-limiting task reduced token usage from 54,000 to 6,840—saving roughly 47,000 tokens, or 87% of the total.

pip install rm-contextos

cd your-project

contextos scan

contextos pack --task "add rate limiting to the auth endpoint" --budget 8000

The CLI outputs a markdown or JSON file with only essential context, complete with a token savings report. No cloud calls are involved, and the tool runs entirely offline on Linux or macOS systems.

Direct integration with AI agents via MCP

Beyond the CLI, ContextOS provides an MCP server that enables seamless tool integration with AI assistants like Claude Desktop and Claude Code. After installing the MCP package, developers can register the server in their configuration and call built-in tools such as pack_context, scan_repo, list_files, and churn_report directly from their AI agent’s interface.

pip install "rm-contextos[mcp]"

contextos serve --stdio

Once registered in claude_desktop_config.json, the AI assistant can invoke these context-aware tools without additional CLI commands. This hands-free approach streamlines workflows in environments where developers rely on natural-language instructions to drive coding tasks.

Open-source foundation and future plans

ContextOS is released under the Apache 2.0 license, with no telemetry or account requirements. The project supports Python versions 3.11 through 3.13 and includes 980 automated tests covering 96% of the codebase. It supports multiple export formats compatible with popular AI coding tools, including Claude, Codex, Cursor, Aider, and raw JSON.

Future improvements may include:

• Support for additional programming languages beyond Python.
• Custom ranking signals based on user feedback.
• Faster incremental scans that ignore unchanged files.
• Enhanced IDE plugins for tighter editor integration.

For developers frustrated by AI assistants that lose track of project context, tools like ContextOS represent a practical step toward precision. By shifting context curation to a static analysis layer, teams can reduce costs, preserve privacy, and maintain focus—without losing the benefits of AI-powered assistance.

What ranking signals would make ContextOS even more useful in your workflow?