universal-context-mode

315 KB becomes 5.4 KB. 98% reduction. Works in every AI IDE.

An open-source MCP server that compresses tool outputs before they enter the AI context window. Built for Claude Code, Cursor, Windsurf, GitHub Copilot, Eclipse, and any MCP-compatible host.

Install in your IDE

Pick your IDE. One command. Done.

Claude Code

claude mcp add context-mode -- npx -y universal-context-mode

Verify:

claude mcp list

Cursor

npx -y universal-context-mode setup cursor

This creates:

• .cursor/mcp.json — registers the MCP server
• .cursor/rules/context-mode.mdc — rules that instruct the agent to use context-mode automatically

Then restart Cursor → open the MCP panel (Ctrl+Shift+P → MCP: Show Panel) to confirm it's connected.

Windsurf

npx -y universal-context-mode setup windsurf

This creates:

• .windsurf/mcp.json — registers the MCP server
• .windsurf/cascade-rules.md — Cascade rules for automatic routing

Then restart Windsurf → Settings → MCP to verify context-mode appears.

GitHub Copilot (VS Code)

npx -y universal-context-mode setup copilot

This updates:

• .vscode/settings.json — adds the MCP server entry
• .github/copilot-instructions.md — custom instructions that guide Copilot to use context-mode

Then reload VS Code (Ctrl+Shift+P → Developer: Reload Window).

Requires VS Code 1.99+ and an active GitHub Copilot subscription.

Eclipse (Embedded C++)

npx -y universal-context-mode setup eclipse

This updates:

• ~/.continue/config.json — registers the MCP server for Continue.dev
• .context-mode/embedded-cpp-rules.md — usage examples for cross-compiler output, linker maps, GDB/OpenOCD, UART logs, and static analysis

Requires Continue.dev plugin and Eclipse 2023-03+ with Java 17+. Install via: Help → Eclipse Marketplace → search "Continue"

Any MCP host

Add this to your MCP configuration file:

{
  "mcpServers": {
    "context-mode": {
      "command": "npx",
      "args": ["-y", "universal-context-mode"]
    }
  }
}

Auto-detect your IDE

Run from your project root — it detects the IDE automatically:

npx -y universal-context-mode setup

What it does

Every AI coding session silently burns context:

You: "Show me recent git commits"
AI:  runs git log  →  150 lines  →  3K tokens gone
You: "Now explain what changed in auth"
AI:  "I've lost context of the earlier conversation..."

context-mode intercepts large outputs and compresses them algorithmically — no LLM calls, no API keys, works offline.

git log (500 commits)   315 KB  →  5.4 KB   (98% saved)
JSON API (500 records)   95 KB  →  0.8 KB   (99% saved)
App logs (1000 lines)    62 KB  →  3.0 KB   (95% saved)
npm list (300 packages)  12 KB  →  1.2 KB   (90% saved)

Your context window stays clean for the entire session instead of exhausting in 30 minutes.

How Much Money This Saves You

Every token wasted on bloated tool output is a token you pay for — and a token that pushes useful context out of the window.

API users (pay-per-token)

| Model | Input price | 1M tokens/day wasted | Monthly waste | |---|---|---|---| | Claude Sonnet | $3 / 1M tokens | ~$3/day | ~$90/month | | GPT-4o | $2.50 / 1M tokens | ~$2.50/day | ~$75/month | | Claude Opus | $15 / 1M tokens | ~$15/day | ~$450/month |

context-mode cuts token consumption by 90–99% on large outputs. A team running 10 AI sessions a day can recover hundreds of dollars per month — just from compression.

Subscription users (Claude Code, Copilot, Cursor)

You pay a flat monthly fee, but hitting the context limit means:

• The session resets — you lose all prior context
• The AI starts making mistakes from missing information
• You spend time re-explaining what was already said

With context-mode, sessions run 3–5× longer before hitting limits. That's 3–5× more productive work per subscription dollar.

Example: a single debugging session

Without context-mode:
  docker logs  →  500 lines  →  62 KB  →  ~15K tokens burned
  git log      →  200 commits →  28 KB  →  ~7K tokens burned
  npm list     →  300 pkgs   →  12 KB  →  ~3K tokens burned
  ─────────────────────────────────────────────────────
  Total wasted: ~25K tokens  ≈  $0.075 per session (Sonnet)
                              ≈  $0.375 per session (Opus)

With context-mode:
  Same 3 commands  →  ~2KB each  →  ~1.5K tokens total
  Savings: 94% — and the full session context stays intact

At 20 debugging sessions per developer per month, that's $1.50–$7.50 saved per developer per month on API costs alone — plus the productivity gain from never losing context mid-session.

Free to use. Zero API calls. Works offline. Pays for itself immediately.

Tools

execute — Run code, get compressed output

execute({
  language: "shell",  // js, ts, python, shell, ruby, go, php, perl, r
  code: "git log --oneline -200",
  intent: "commits related to authentication"  // optional — filters output
})

Supports 10 runtimes. Bun auto-detected for 3–5× faster JS/TS execution. Output is compressed before entering context.

execute_file — Process large files without loading them

execute_file({
  file_path: "/path/to/package-lock.json",
  code: `
    const d = JSON.parse(process.env.FILE_CONTENT);
    console.log('Packages:', Object.keys(d.dependencies ?? {}).length);
  `
})

File content injected via FILE_CONTENT env var. Only your summary enters context.

index — Index content into searchable knowledge base

index({
  content: largeDocumentation,
  source: "api-reference.md",
  kb_name: "project-docs"
})

SQLite with BM25 ranking + Porter stemming. Heading-aware chunking. Code blocks preserved.

search — Query indexed content

search({
  query: "authentication middleware configuration",
  kb_name: "project-docs",
  top_k: 5
})

Returns relevant snippets with heading context — never full documents.

fetch_and_index — Fetch a URL and index it

fetch_and_index({ url: "https://angular.io/guide/signals", kb_name: "angular" })
search({ query: "computed signals", kb_name: "angular" })

Private/authenticated URLs supported via headers:

fetch_and_index({
  url: "https://api.github.com/repos/org/repo/readme",
  kb_name: "project-docs",
  headers: { "Authorization": "Bearer ghp_xxx" }
})

HTML → Markdown conversion. Raw content never enters context.

compress — Compress any large text

compress({
  content: anyLargeText,
  intent: "find error messages and stack traces",
  strategy: "auto"  // auto | truncate | summarize | filter
})

Auto-detects content type and applies the best strategy:

| Type | Examples | |---|---| | JSON | API responses, config files | | Logs | app logs, docker logs, syslog | | Code | JS/TS/Python/Go/Rust/C++ source | | Markdown | docs, READMEs, wikis | | CSV | exports, reports | | YAML/TOML | docker-compose, Cargo.toml, CI configs | | XML | pom.xml, AndroidManifest, .cproject | | Diff | git diff output — shows files + context, strips line noise | | Stack trace | JS/Python/Rust/C++ crashes — extracts root cause, collapses frames | | Env/INI | .env, .ini files — shows keys, masks secrets automatically |

proxy — Wrap any tool call and compress its output

proxy({
  tool: "bash",
  args: { command: "docker logs my-container --tail 500" },
  intent: "connection errors"
})

The key differentiator for IDEs without PreToolUse hooks.

report — Show how much context was saved this session

report()

Returns a per-request token tracking summary (input tokens seen, output before→after compression) plus persistent today/all-time totals. Use it to verify context-mode is working.

=== context-mode Session Report ===

Session: 23m | 12 requests | 5 compressions

PER-REQUEST TOKEN TRACKING
  Total requests:  12
  Input tokens:       148 tokens  (512 B sent to tools)
  Output tokens:   11.3K tokens → 2.0K tokens (compressed)
  Net tokens saved: 9.3K tokens

COMPRESSION SAVINGS
  Before:       45.2 KB  (~11.3K tokens)
  After:         8.1 KB  (~2.0K tokens)
  Saved:        37.1 KB  (~9.3K tokens)
  Ratio:        82.1% reduction

BY TOOL
  compress         3x    28.4 KB saved  (~7.1K tokens)
  fetch_and_index  2x     8.7 KB saved  (~2.2K tokens)


HISTORICAL
  Today      112.3 KB  (~28.1K tokens)  across 4 sessions
  All time   843.1 KB  (~210.8K tokens) across 23 sessions

STATUS: ✓ Working — saved 37.1 KB from context window this session

Historical stats persist across server restarts in ~/.ucm-stats.json.

Benchmarks

| Content | Input | Output | Saved | |---|---|---|---| | git log — 500 commits | 28 KB | 4 KB | 86% | | JSON API — 500 records | 95 KB | 0.8 KB | 99% | | App logs — 1000 lines | 62 KB | 3 KB | 95% | | Markdown docs — 15 sections | 48 KB | 2 KB | 96% | | CSV export — 500 rows | 22 KB | 0.6 KB | 97% | | npm list — 300 packages | 12 KB | 1.2 KB | 90% | | TypeScript — 30 methods | 18 KB | 3 KB | 83% | | YAML — docker-compose (200 lines) | 8 KB | 1.5 KB | 81% | | git diff — 50 files changed | 42 KB | 13 KB | 69% | | Stack trace — Java exception | 6 KB | 0.5 KB | 91% | | .env — 80 keys (secrets masked) | 4 KB | 1.2 KB | 70% |

All algorithmic. No LLM. No API key. Works offline. See BENCHMARK.md.

Configuration

Set via environment variables — no config file needed:

| Variable | Default | Description | |---|---|---| | UCM_THRESHOLD_BYTES | 5120 | Skip compression below this size | | UCM_MAX_OUTPUT_BYTES | 8192 | Target max output size | | UCM_TIMEOUT_MS | 30000 | Sandbox execution timeout (ms) | | UCM_DB_PATH | OS temp dir | SQLite database path | | LOG_LEVEL | info | debug / info / warn / error |

Example — lower the output target to 4 KB:

UCM_MAX_OUTPUT_BYTES=4096 npx -y universal-context-mode

Requirements

• Node.js 18+ (LTS or current)
• No Python, no build tools — pure JS/WASM stack, installs in seconds
• Bun optional — auto-detected, gives 3–5× faster JS/TS execution

Contributing

Local dev setup

# 1. Fork on GitHub, then clone your fork
git clone https://github.com/phanindra208/universal-context-mode.git
cd universal-context-mode

# 2. Install (no native compilation — pure JS/WASM)
npm install

# 3. Build TypeScript
npm run build

# 4. Run tests
npm test

# 5. Watch mode while developing
npm run test:watch

Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js
# Opens browser UI at http://localhost:5173
# Call any of the 8 tools interactively

Point your IDE at your local build

Instead of the published npm package, use your local dist:

{
  "mcpServers": {
    "context-mode": {
      "command": "node",
      "args": ["/absolute/path/to/universal-context-mode/dist/index.js"]
    }
  }
}

For Claude Code:

claude mcp add context-mode -- node /absolute/path/to/universal-context-mode/dist/index.js

Useful commands

npm run lint          # ESLint
npm run lint:fix      # Auto-fix
npm run format        # Prettier
npm run build         # tsc compile
npm test              # vitest (unit + integration, 75+ tests)
npm run test:watch    # Watch mode
npm run benchmark     # Regenerate BENCHMARK.md

Project layout

src/
├── compression/      ← Add new content-type strategies here
│   ├── strategies.ts    detectContentType() + compress() pipeline
│   ├── intent-filter.ts TF-IDF relevance scoring
│   └── chunker.ts       Markdown-aware splitter
├── knowledge-base/   ← SQLite BM25 (sql.js, pure WASM — no node-gyp)
├── sandbox/          ← Subprocess execution + 10 runtime detectors
├── adapters/         ← Add a new IDE adapter here
├── tools/            ← 8 MCP tool implementations
└── utils/

tests/
├── unit/             one file per module
├── integration/      full MCP protocol round-trips
└── benchmarks/       compression ratio assertions

Adding a new compression strategy

1. Add your function to src/compression/strategies.ts
2. Register in detectContentType() and the compress() switch
3. Write tests in tests/unit/compression.test.ts
4. Add a benchmark in tests/benchmarks/compression-ratio.test.ts

Adding a new IDE adapter

1. Create src/adapters/your-ide.ts implementing BaseAdapter
2. Register in src/adapters/generic.ts
3. Add templates under templates/your-ide/
4. Add a script scripts/setup-your-ide.sh

See CONTRIBUTING.md for the PR process and TDD guide.

Publishing (maintainers)

npm version patch   # or minor / major
git push --tags     # triggers CI → auto-publishes to npm

The release workflow (.github/workflows/release.yml) handles npm publish on every v*.*.* tag.

License

MIT — see LICENSE

Inspired by

mksglu/claude-context-mode — the original Claude Code-specific implementation that inspired this universal version.