pip install contextos-dd && contextos install

✨ What it does

Every long Claude Code, Cursor, or Codex session resends the entire conversation history to Anthropic or OpenAI on every turn — that's where your token bill comes from. ContextOS is the local-first LLM context window manager that fixes this: it runs as a tiny FastAPI proxy on 127.0.0.1, classifies each turn HOT / WARM / COLD / DEAD by relevance, drops duplicates, and replaces stale runs with summaries — all on your machine, with no telemetry and no cloud sync.

🚀 60-second install

pip install contextos-dd
contextos install

That single command:

1. 🔍 Detects supported IDE configs (Claude Code, Cursor, Codex CLI, Continue, Aider)
2. 💾 Backs them up to ~/.contextos/backups/
3. 🔌 Patches them to route through the local proxy on 127.0.0.1:9137
4. 📥 Downloads two small models (~430 MB, one time) to ~/.contextos/models/
5. ▶️ Starts the daemon and opens the dashboard in your browser

💡 Offline / air-gapped? Use contextos install --skip-models. Models download on first compaction.

📖 See INSTALL.md for the full walkthrough.

🧬 How it works

┌────────────┐    raw history     ┌────────────────┐    trimmed payload   ┌──────────────┐
│ Claude Code│ ─────────────────► │   ContextOS    │ ───────────────────► │  Anthropic   │
│   Cursor   │                    │   (localhost   │                      │   OpenAI     │
│   Codex    │ ◄───────────────── │     :9137)     │ ◄─────────────────── │              │
└────────────┘    streamed reply  └────────┬───────┘     full response    └──────────────┘
                                            │
                                  ┌─────────┴──────────┐
                                  │  Local DuckDB +    │
                                  │  Qwen2.5-0.5B +    │
                                  │  bge-small-en      │
                                  └────────────────────┘

Every turn in your conversation is tagged by heat:

Trigger phrases like "as we discussed earlier" fire a vector recall from a local LanceDB store and re-inject the missing context on the next turn — so summarized history is still semantically retrievable.

🎛️ Commands

📦 What gets downloaded

One time. Lives on disk forever. Re-pull anytime with contextos warmup.

🔐 Privacy

ContextOS is local-first by construction:

• 🚫 No telemetry. Zero. We do not phone home.
• 🚫 No cloud sync. Sessions, summaries, embeddings, logs — all in ~/.contextos/ on your machine.
• 🚫 No background uploads. Ever.
• ✅ Your code never reaches a third party. The only outbound call ContextOS makes is forwarding your IDE's request to the LLM you already chose.

The only network traffic ContextOS initiates on its own:

• Model downloads during install / warmup (from HuggingFace)
• Forwarding your IDE's chat requests upstream — the same request your IDE was going to send anyway, just smaller.

📁 Where stuff lives

~/.contextos/                       (Windows: %LOCALAPPDATA%\DataDojo\contextos\)
├── ledger.duckdb                   # append-only session + turn ledger
├── daemon.pid                      # daemon process id
├── dashboard.pid                   # dashboard process id
├── backups/                        # snapshots: ledger backups + IDE config backups
│   ├── ledger-20260517-091944.duckdb
│   └── settings.json.<ts>.bak
├── archive/                        # LanceDB vector store of compacted turns
├── models/                         # Qwen2.5 GGUF + bge-small ONNX
└── logs/
    ├── contextos.log               # rolling app log (10MB × 5)
    ├── daemon.stdout.log
    └── daemon.stderr.log

contextos uninstall restores IDE configs and stops the daemon. It does not delete the ledger or models — they stay in case you reinstall. Nuke everything by deleting the directory above.

🩹 Troubleshooting

contextos start --foreground

# Windows
set CONTEXTOS_PASSTHROUGH=1
contextos stop && contextos start

# macOS / Linux
export CONTEXTOS_PASSTHROUGH=1
contextos stop && contextos start

contextos uninstall    # restores original IDE configs

contextos status                        # find your session id
contextos export <session_id> --out my_history.json

pip install 'contextos-dd[dashboard]'

🛣️ Roadmap

🛠️ Develop

git clone https://github.com/skappal7/context-os
cd context-os
pip install -e ".[dev,dashboard]"
ruff check .
pytest -q

55 tests across the proxy, classifier, compactor, ledger, dashboard, and safety layer. Includes a realistic Claude Code fixture (tool_use + tool_result + cache_control) that locks in the v0.1.3 regression fix.

📜 License & credits

Apache-2.0. Built by DataDojo.

Vendored under the hood: FastAPI · DuckDB · LanceDB · llama.cpp (via llama-cpp-python) · fastembed · Qwen2.5 · BAAI/bge-small-en · Streamlit.