DEV Community

Rohith Matam
Rohith Matam

Posted on

I built a "context OS" that stops AI agents from drowning in your codebase

#ai #opensource #productivity #python

The problem every AI coding session hits

You open Claude or Copilot, paste in your task, and immediately hit the wall: the codebase is too big. You either:

  • Dump everything and burn 80% of your context window on irrelevant files
  • Hand-pick files and miss the one import that breaks everything
  • Pay for a bigger context window and repeat the problem at scale

I got tired of this and built ContextOS — a local CLI that acts as an intelligent context layer between your repo and your AI agent.

What it does 

pip install rm-contextos
cd your-project
contextos scan
contextos pack --task "add rate limiting to the auth endpoint" --budget 8000
Enter fullscreen mode Exit fullscreen mode

Output: a Markdown (or JSON) context pack with only the files that matter for that task — ranked by keyword match, import graph centrality, AST symbol overlap, and git churn. Secrets redacted automatically.

Token savings report on every pack:

Packed 12 files · ~6,840 tokens · saved ~47,200 tokens (87%) vs full repo
Enter fullscreen mode Exit fullscreen mode

How ranking works

Five signals combine into a score per file:

Signal What it catches
Keyword match Files whose content/name overlap with your task
Import graph centrality Files that everything else imports (critical shared modules)
AST symbol overlap Function/class names, not just grep strings
Git churn score Recently modified files are probably active code
Secret penalty Credential files silently excluded

No LLM calls. No cloud. Fully offline.

MCP server (for Claude Desktop / Claude Code) 

pip install "rm-contextos[mcp]"
contextos serve --stdio
Enter fullscreen mode Exit fullscreen mode

Register in claude_desktop_config.json and your AI agent can call pack_context, scan_repo, list_files, get_file, churn_report directly as tools — no CLI needed.

What's shipped

  • 980 tests, 96% coverage
  • Apache-2.0, no telemetry, no accounts
  • Python 3.11–3.13, Linux + macOS
  • Export formats: Claude, Codex, Cursor, Aider, JSON
  • Incremental scan cache — re-scans only changed files 
pip install rm-contextos
pip install "rm-contextos[mcp]"   # + MCP server
pip install "rm-contextos[all]"   # everything
Enter fullscreen mode Exit fullscreen mode

GitHub: https://github.com/Rohithmatham12/ContextOS
Docs: https://Rohithmatham12.github.io/ContextOS/

Would love feedback — especially on the ranking signals and MCP integration. What signals are you missing?

Top comments (0)