context-guardian

<h1 align="center">Context Guardian</h1>

<p align="center"><b>Your local-model session hits the context limit and dies. This stops that.</b></p>

<p align="center">
  <a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/test.yml"><img alt="tests (pytest) on Ubuntu, Windows, macOS" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/test.yml/badge.svg"></a>
  <a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/node.yml"><img alt="node smoke tests on Ubuntu, Windows, macOS" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/node.yml/badge.svg"></a>
  <a href="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/privacy.yml"><img alt="privacy scan of every tracked file" src="https://github.com/LuminariSoftwares/context-guardian/actions/workflows/privacy.yml/badge.svg"></a>
  <a href="https://pypi.org/project/context-guardian/"><img alt="PyPI" src="https://img.shields.io/pypi/v/context-guardian.svg"></a>
  <a href="https://www.npmjs.com/package/dsh-context-guardian"><img alt="npm" src="https://img.shields.io/npm/v/dsh-context-guardian.svg"></a>
  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-yellow.svg">
  <img alt="Python 3.11" src="https://img.shields.io/badge/python-3.11-blue.svg">
  <img alt="OpenAI-compatible proxy" src="https://img.shields.io/badge/OpenAI--compatible-proxy-2ea44f.svg">
  <img alt="DeepSeek Harness engine" src="https://img.shields.io/badge/DSH-compaction%20engine-0969da.svg">
  <img alt="Fails open" src="https://img.shields.io/badge/fails-open-6f42c1.svg">
</p>

mcp-name: io.github.LuminariSoftwares/context-guardian

<p align="center">
  <a href="#quick-start">Quick start</a> &middot;
  <a href="#works-with">Works with</a> &middot;
  <a href="#point-your-client-at-the-proxy">Client settings</a> &middot;
  <a href="examples/">Examples</a> &middot;
  <a href="#install-both-deepseek-harness-about-5-minutes">Install both</a> &middot;
  <a href="#why-this-exists">Why</a> &middot;
  <a href="#two-ways-to-run-it">Two ways to run it</a> &middot;
  <a href="#install">Install the proxy</a> &middot;
  <a href="docs/dsh-integration.md">Install in DSH</a> &middot;
  <a href="#see-it-work">See it work</a> &middot;
  <a href="#compatibility">Compatibility</a> &middot;
  <a href="CHANGELOG.md">Changelog</a>
</p>

Compaction for local models that actually fires, and never takes the conversation down with it. Two front doors, one idea: a **proxy** that sits in front of any OpenAI-compatible backend (Ollama, LiteLLM, Headroom, vLLM, LM Studio) for any CLI or agent, and a **native engine** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). Both keep the full original on disk, and both fail **open**.

**Measured:** in a 48-prompt DeepSeek Harness session on qwen3-coder:30b (Ollama, 64K window) with codenames changed mid-session, 0.1.0-alpha.9 kept 12/12 facts current with 0 stale answers and brought back 3/3 early details in every run (n = 3), where pins alone brought back 0/3 (n = 2). Details: [Measured](#measured-does-it-keep-what-matters-2026-10-01).

## Works with

| | how it hooks in | status | example |
|---|---|---|---|
| **Ollama** | proxy: `GUARDIAN_UPSTREAM_URL=http://localhost:11434/v1` | tested (daily use, Windows 11) | [examples/ollama-proxy](examples/ollama-proxy/) |
| **LM Studio** | proxy: `GUARDIAN_UPSTREAM_URL=http://localhost:1234/v1` | expected to work, not tested against LM Studio itself | [examples/lmstudio-proxy](examples/lmstudio-proxy/) |
| **vLLM** | proxy: `GUARDIAN_UPSTREAM_URL=http://localhost:8000/v1` | expected to work, untested | copy the Ollama example, change the URL |
| **LiteLLM** | proxy: `GUARDIAN_UPSTREAM_URL=<your LiteLLM proxy>/v1` | expected to work, untested | copy the Ollama example, change the URL |
| **DeepSeek Harness** | native engine: one row in your agent preset | tested on DSH 0.1.2-alpha.2 | [examples/dsh-preset](examples/dsh-preset/) |

The proxy needs only an OpenAI-compatible `/v1/chat/completions`; your CLI points `OPENAI_BASE_URL` at it. "Expected" means not yet tested; please open an issue with what you saw. Full matrix: [Compatibility](#compatibility).

## Quick start

```bash
pip install context-guardian && context-guardian   # proxy on :8786 in front of Ollama on :11434; set OPENAI_BASE_URL=http://localhost:8786/v1
context-guardian-doctor                            # second terminal: checks the install and the running proxy, prints a fix: line for anything wrong
```

Another backend or window: see [examples/](examples/) or [Configure](#configure). Your client's settings: [Point your client at the proxy](#point-your-client-at-the-proxy). DeepSeek Harness users: install the native engine below.

After a compaction, `context-guardian-recall "<term>"` searches the archived originals (the summary the model receives names the exact command).

## Point your client at the proxy

The proxy compacts OpenAI-style `POST /v1/chat/completions` requests. Every client below is configured from its own documented settings; none of these four has been tested against the proxy yet, so please open an issue with what you see.

| client | where | what to set |
|---|---|---|
| **Claude Code** | environment | Claude Code speaks the Anthropic Messages API (`/v1/messages`). The proxy compacts it too when `GUARDIAN_UPSTREAM_URL` serves that API (the summary call goes to the same upstream's `/messages` with your key and goes into `system`): `ANTHROPIC_BASE_URL=http://localhost:8786`. Or use an OpenAI-compatible build such as OpenClaude: `CLAUDE_CODE_USE_OPENAI=1 OPENAI_BASE_URL=http://localhost:8786/v1 OPENAI_API_KEY=local OPENAI_MODEL=<model>` |
| **Cline** | Settings → API Provider: **OpenAI Compatible** | Base URL `http://localhost:8786/v1` · API Key any non-empty text · Model ID `<model>` |
| **Continue** | `~/.continue/config.yaml` | under `models:` add `- {name: Context Guardian, provider: openai, model: <model>, apiBase: "http://localhost:8786/v1", apiKey: local}` |
| **OpenCode** | `opencode.json` | `"provider": {"guardian": {"npm": "@ai-sdk/openai-compatible", "name": "Context Guardian", "options": {"baseURL": "http://localhost:8786/v1"}, "models": {"<model>": {}}}}` |

`<model>` is the name your backend serves (for Ollama, what `ollama list` shows). The proxy forwards the API key unchanged; a local backend ignores it. Then set `GUARDIAN_NUM_CTX` to that model's real window ([Configure](#configure)).

![Illustration of Context Guardian inside DeepSeek Harness: the context meter climbs to the 85 % line, compaction folds the old turns into a checkpoint with the pinned facts first, and later stale recall brings back an archived line](context_guardian_dsh_demo.gif)

*An illustration of what the DSH engine (0.1.0-alpha.9) does, not a DSH screen. Inside DSH you see it as DSH's own "Context compacted" row and context meter, `/context` and `/guardian` for pressure and the last compaction, and the `[context-guardian recall]` message in the conversation. What happens: at 85 % of the window it compacts, the facts you asked it to keep lead every checkpoint, the old turns stay on disk, and when a later question needs a detail that was compacted away, stale recall puts the original line back before the model answers. The results line is the benchmark in [Measured](#measured-does-it-keep-what-matters-2026-10-01). The proxy has its own monitor: see [See it work](#see-it-work).*

| | Without Context Guardian | With it |
|---|---|---|
| Claude-Code-style CLI on a local model | auto-compact never fires; the backend hard-rejects the request and the session is over | the proxy compacts before the window fills; the session keeps going |
| DSH on a 32K local model (measured: 314 compaction attempts) | **48 succeeded**; the rest failed on an empty summary or overflowed the window *while summarising* | every failed or impossible summary falls back to a deterministic checkpoint: ~14,012 → ~584 tokens in 23 ms, no model call |
| The part that was compacted away | gone | archived on disk; in DSH every checkpoint line carries a `seq` pointer that `recall` reads back |

## Install both (DeepSeek Harness, about 5 minutes)

Context Guardian and Tool Guardian are two halves of one problem: **Tool Guardian** keeps tool schemas and tool results from filling the window, and **Context Guardian** compacts the conversation before it fills and keeps what matters. They share no files and install separately. You need DSH 0.1.2-alpha.2 or later, Node.js `^22.19` or `>=24`, and Python 3.9+ on `PATH` for Tool Guardian's router.

```bash
# 1. Add both bundles to the DSH profile you use (`web` is the one `dsh web` uses)
dsh plugin --profile web add dsh-tool-guardian
dsh plugin --profile web add dsh-context-guardian

# 2. Tool Guardian: copy in the MCP servers you already use (Claude Desktop / Cursor / Windsurf / .mcp.json), then check them
cd ~/.dsh/profiles/web/node_modules/dsh-tool-guardian          # Windows: cd %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-tool-guardian
npm run setup                  # asks before it writes ~/.tool-guardian/mcp.json, then prints a doctor report

# 3. Context Guardian: add its compaction row to your agent preset (a dry run until --apply)
cd ~/.dsh/profiles/web/node_modules/dsh-context-guardian       # Windows: cd %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-context-guardian
npm run setup
npm run setup -- --apply

# 4. Start DSH and open a NEW session with the preset setup named
dsh web
```

In that session, type `/guardian`. It shows Context Guardian's engine revision and your model's window. Then type `/toolguardian`. It shows each MCP server Tool Guardian started, the tokens the router saves on every request, and whether an update is out.

Not on DSH? Context Guardian's proxy (`python context_guardian.py`, see its README) works with any OpenAI-compatible CLI. Tool Guardian runs as a plain MCP server fo