Context Cooler
Context Cooler β eliminate token burn with the coolest MCP on the net. Sandboxed exec in 11 languages, FTS5 search, multi-messenger delivery, 5 platform adapters. MIT, zero callbacks.
Ask AI about Context Cooler
Powered by Claude Β· Grounded in docs
I know everything about Context Cooler. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Context Cooler v5.1
Eliminate token burn with the coolest MCP on the net.
Burn fewer tokens. Ship cooler agents.
A standalone Model Context Protocol (MCP) server that gives any MCP-compatible coding agent β Claude Code, Cursor, OpenAI Codex CLI, Gemini CLI, OpenCode β a sandboxed runtime, an FTS5 knowledge base, and a multi-messenger delivery channel. Built from scratch on the MCP spec. Zero outbound dependencies beyond the four pinned ones in package.json. MIT-licensed, audit-readable end-to-end.
The "Think in Code" philosophy
When an agent needs to analyse a directory, a JSON dump, or 47 source files, the temptation is to Read every file and let the model figure it out from raw text. That's how 750 KB of cached context disappears in a single afternoon: every turn re-pays the read cost.
Don't pull data into the model. Push code at the data and pull back the answer.
Canonical example
"Across these 47 TypeScript files, find every
awaitthat's missing atry/catch."
| Approach | Bytes consumed | Tokens (rough) |
|---|---|---|
Read Γ 47 (/src/**/*.ts) | ~700 KB raw text in context | ~175,000 |
ctx_execute (one shell+grep call, prints summary) | ~3.6 KB summary | ~900 |
The 195Γ reduction isn't theoretical β it's what the existing OpenClaw morning-brief pipeline measures every day. The agent's job is to write a script, not to memorise the repo.
ctx_execute runs that script in a sandboxed subprocess (11 supported runtimes), captures stdout, optionally filters with an intent keyword, indexes the full output in FTS5 (so the agent can search it later without re-reading), and returns only the compact summary to the context window.
What's new in v5.1
- Installs on any machine β OpenClaw no longer required.
install.pypreviously aborted withOpenClaw home not foundif~/.openclawwas missing. The installer now auto-creates the data directory, defaults to running only the universally relevant steps (build MCP server, register adapter, init SQLite DBs, record upgrade timestamp), and skips the OpenClaw-specific script copy + AGENTS.md / TOOLS.md / cron patches when no OpenClaw workspace is detected. Pure no-op for non-OpenClaw users; identical behaviour for OpenClaw users. --data-dirflag added as a clearer alias for--openclaw-home(the old flag still works for back-compat).
What's new in v4.6
- Platform adapters β one-shot installers for Claude Code, Cursor, OpenAI Codex CLI, Gemini CLI, and OpenCode. Pick one or all of them at install time. See "Platform adapters".
- Exit classification β
ctx_executenow returns a structuredstatus:success | runtime_error | timeout | sandbox_violation | language_unavailable. Agents can branch on the failure mode instead of parsing stderr. - Local update reminder β
ctx_doctorreads~/.context-cooler/last-upgrade.txt(purely local, no network call) and surfaces a "last upgraded N days ago" warning when it's older than 30 days. - Polished installer β
install.pynow walks you through platform selection and install path interactively (stdlibinput(), no new dependencies). Non-TTY runs default to all platforms. - Backwards compatible β every v4.5 tool keeps the same name, schema, and on-success response shape. The new fields (
status,exit_code,duration_ms) are additive.
Installation & Updates
macOS / Linux
First-time install:
git clone https://github.com/tlancas25/context-cooler.git
cd context-cooler
python3 install.py
Update to the latest version:
cd context-cooler
python3 install.py --update
Windows
First-time install:
git clone https://github.com/tlancas25/context-cooler.git
cd context-cooler
python install.py
Update to the latest version:
cd context-cooler
python install.py --update
Windows notes: iMessage delivery is macOS-only. Telegram, Slack, and Discord work on all platforms. For full shell sandboxing support, install WSL (
wsl --install) and run the installer from inside WSL.
Installer Options
python3 install.py # Interactive β asks which agents to register
python3 install.py --platform=claude-code # Register one platform, skip prompt
python3 install.py --platform=all # Register every supported agent
python3 install.py --non-interactive # Use defaults, no prompts (for CI)
python3 install.py --dry-run # Preview changes without writing
python3 install.py --verify # Check installation status
python3 install.py --uninstall # Remove context-saver wiring
python3 install.py --update # git pull + rebuild + re-register
python3 install.py --accept-disclaimer # Skip disclaimer prompt (CI/scripts)
python3 install.py --skip-cron # Don't patch cron jobs
python3 install.py --skip-agents # Don't patch AGENTS.md
python3 install.py --skip-tools # Don't patch TOOLS.md
python3 install.py --data-dir /custom/path # Custom data directory (alias: --openclaw-home)
What the Installer Does
Always (every machine):
- Builds the MCP server (
npm install+npx tsc). - Registers
context-coolerwith each selected platform adapter (Claude Code, Cursor, Codex, Gemini, OpenCode). Each adapter writes atomically (tmp file + rename) to that platform's MCP config file. - Initialises SQLite databases (
stats.db+sessions.db) under the data directory (default~/.openclaw, override with--data-dir). The directory is auto-created β no need for OpenClaw to be installed. - Records the install timestamp in
~/.context-cooler/last-upgrade.txtsoctx_doctorcan remind you to upgrade later.
Optional β only when the OpenClaw workspace is detected (skipped automatically on machines without OpenClaw):
- Copies the legacy python helpers into
~/.openclaw/workspace/skills/context-saver/. - Patches
AGENTS.mdwith mandatory Context Saver Protocol rules. - Patches
TOOLS.mdwith quick-reference commands. - Patches cron jobs to route data-heavy skill calls through context-saver.
Requirements
- Node.js 18+ (for the MCP server)
- Python 3.8+ (for the installer and helper scripts β stdlib only, no pip dependencies)
- SQLite (bundled with Python and Node.js via better-sqlite3)
Platform adapters
Each adapter writes a single MCP-server entry (stdio, command node, args [abs-path-to-dist/server.js]) into the configuration file the host actually reads. Atomic write: tmp file + rename. Dry-run prints the path it would write to, then exits without touching disk.
| Platform | Config file written | Adapter |
|---|---|---|
| Claude Code | ~/.claude.json (mcpServers map) | src/adapters/claude-code.ts |
| Cursor | ~/.cursor/mcp.json (mcpServers map) | src/adapters/cursor.ts |
| OpenAI Codex CLI | ~/.codex/mcp_servers.json (mcpServers map) | src/adapters/codex.ts |
| Gemini CLI | ~/.gemini/settings.json (mcpServers map) | src/adapters/gemini.ts |
| OpenCode | ~/.config/opencode/opencode.json (mcp map) | src/adapters/opencode.ts |
Each adapter is under 80 lines and only depends on Node stdlib. They are also reachable from the command line for scripted installs:
node dist/adapters/index.js list
# {"adapters":["claude-code","cursor","codex","gemini","opencode"]}
node dist/adapters/index.js install \
--server="$(pwd)/dist/server.js" \
--platform=cursor \
--dry-run
# {"platform":"cursor","configPath":"/Users/you/.cursor/mcp.json","ok":true,"detail":"would register context-cooler -> ..."}
install.py calls this CLI under the hood, one platform at a time.
Architecture
Context Saver is a single MCP server that any MCP-compatible agent auto-discovers. When the agent needs to run code, search data, or deliver messages, it calls our tools directly β there's nothing to skip or bypass.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ANY MCP-Compatible AI Agent β
β Claude Code / Cursor / Codex / Gemini CLI / OpenCode / Custom β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ
β
MCP Protocol (stdio)
β
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββ
β context-cooler (Node.js MCP Server) β
β β
β 10 Tools: Core Libraries: β
β β’ ctx_execute (sandbox) β’ sandbox.ts (11 languages) β
β β’ ctx_execute_file (file inject) β’ exit-classify.ts (status) β
β β’ ctx_batch (multi-cmd) β’ filter.ts (intent scoring)β
β β’ ctx_search (FTS5 query) β’ db.ts (SQLite + FTS5) β
β β’ ctx_index (store data) β’ chunker.ts (markdown/JSON) β
β β’ ctx_fetch_index (HTTPβindex) β’ redact.ts (secret strip) β
β β’ ctx_session (P1-P4 state) β’ env.ts (config loader) β
β β’ ctx_stats (aggregation) β
β β’ ctx_deliver (4 backends) Adapters (v4.6): β
β β’ ctx_doctor (health check) β’ claude-code / cursor / β
β codex / gemini / opencode β
β Databases: β
β β’ stats.db (runs + fts_index) β
β β’ sessions.db (events + snapshots) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
Compact output (100-500 B)
instead of raw dump (3-50 KB)
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Agent Context Window β
β 70-98% smaller than raw API responses β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
MCP Registration
After install, every selected platform's config file ends up with an entry like this (Claude Code shown):
{
"mcpServers": {
"context-cooler": {
"type": "stdio",
"command": "node",
"args": ["/path/to/context-cooler/dist/server.js"],
"env": {}
}
}
}
Any MCP client (Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode) auto-discovers the 10 tools and calls them natively.
The 10 MCP Tools
ctx_execute β Sandboxed Code Execution
Run code in 11 languages with intent-driven output filtering. Full output is indexed in FTS5; only the filtered summary enters the context window.
Supported languages: JavaScript, TypeScript, Python, Shell, Ruby, PHP, Perl, Go, Rust, R, Elixir.
ctx_execute(language="python", code="...", intent="check balance")
β 120 B summary instead of 3 KB raw dump
v4.6 structured result. Every call returns:
{
"success": true,
"status": "success", // success | runtime_error | timeout | sandbox_violation | language_unavailable
"exit_code": 0,
"duration_ms": 47,
"summary": { ... }, // or "output": "..." for non-JSON stdout
"raw_bytes": 3127,
"summary_bytes": 96,
"bytes_saved": 3031,
"savings_pct": 96.9,
"indexed": true,
"stderr": "..." // present only when stderr is non-empty
}
Status semantics:
| Status | When |
|---|---|
success | Process exited 0. |
runtime_error | Non-zero exit, no other classifier matched. |
timeout | Killed because args.timeout elapsed. |
sandbox_violation | Non-zero exit + stderr matched a kernel/sandbox block pattern (operation not permitted, seccomp, EPERM, sandbox-exec ... deny). |
language_unavailable | The runtime executable wasn't on PATH (spawn ENOENT, command not found). |
ctx_execute_file β File-Aware Execution
Same as ctx_execute but injects a file's content as a variable (FILE_CONTENT) into the execution environment.
ctx_batch β Multi-Command Pipeline
Run multiple commands and/or search queries in a single MCP call. Each command is executed sequentially with its own intent filter.
ctx_batch(commands=[
{"language": "python", "code": "...", "intent": "summary"},
{"language": "shell", "code": "...", "intent": "top 5"}
], queries=["previous error rates"])
ctx_search β FTS5 Knowledge Base Query
Search previously indexed data using SQLite FTS5 with BM25 ranking. Supports phrase matching, boolean operators, and prefix queries.
ctx_search(queries=["deployment errors", "position changes"])
ctx_index β Store Data in Knowledge Base
Index content (text, JSON, or file paths) into FTS5 with automatic chunking. Markdown is chunked by headings, JSON by key paths, plain text by 50-line blocks. 4096 byte max per chunk, 100 KB per entry, 10 K max rows with auto-pruning.
ctx_fetch_index β HTTP Fetch + Index
Fetch a URL, convert HTML to markdown (via Turndown), and index the content. Follows redirects, enforces 1 MB cap.
ctx_fetch_index(url="https://docs.example.com/api", source="API docs")
ctx_session β Session Continuity
Log events with P1-P4 priority, take snapshots before compaction, and restore state after. Snapshots fit within a strict 2 KB budget (40% P1 / 30% P2 / 20% P3 / 10% P4).
ctx_session(action="log", event_type="decision", priority="high", data={...})
ctx_session(action="snapshot") # Before compaction
ctx_session(action="restore") # After compaction
ctx_session(action="stats") # Event counts and sizes
ctx_stats β Usage Aggregation
Aggregate stats across both stats.db and sessions.db. Shows total runs, bytes saved, compression ratios, and session event counts.
ctx_deliver β Multi-Messenger Delivery
Send messages via iMessage (macOS), Telegram, Slack, or Discord. Auto-detects available backend based on environment variables.
| Backend | Requirement | Platform |
|---|---|---|
| iMessage | imsg CLI | macOS only |
| Telegram | TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID | All |
| Slack | SLACK_WEBHOOK_URL | All |
| Discord | DISCORD_WEBHOOK_URL | All |
ctx_doctor β Health Check
Checks OPENCLAW_HOME, databases, FTS5 tables, skills directory, 5 language runtimes, mcporter availability, all 4 delivery backends, and (v4.6) the local upgrade reminder. Returns a pass/warn/fail report.
The upgrade reminder reads ~/.context-cooler/last-upgrade.txt (an ISO 8601 timestamp written by install.py), compares it to today, and surfaces a warn if it's older than 30 days. No network call β this is purely a local file comparison.
Token Protection Layers
Layer 1: Sandboxed Execution + Filtering
Every code execution goes through ctx_execute. The full output is captured, filtered by intent, and indexed. Only the compact summary (100-500 bytes) enters the context window.
Agent β ctx_execute β sandbox (11 langs) β intent filter β 120 B summary
β
FTS5 index (full data preserved)
Layer 2: Compact-by-Default Skills
Skills return minimal output by default. --verbose is required for full data. ctx_execute auto-injects --verbose so it gets the full data to filter, but only returns the compact result.
# Default: 3 fields per item (~80 bytes)
{"s": "AAPL", "qty": "100", "pnl": "1500.00"}
# Verbose (only ctx_execute sees this): 12+ fields (~350 bytes)
{"symbol": "AAPL", "qty": "100", "side": "long", "market_value": "18500", ...}
Layer 3: Intent-Driven Filtering
Pass an intent string and Context Saver extracts only matching fields using fast keyword scoring:
"check balance"β returns equity, buying_power, cash (3 fields out of 40+)"find losing"β returns only positions with negative P&L"top 5 movers"β returns top 5 items sorted by change
Smart wrapper dict handling: {"count": 8, "positions": [...]} β automatically unwraps and recurses.
Layer 4: Session Continuity
P1-P4 priority events survive conversation compaction via 2 KB snapshots stored in SQLite. Critical decisions and alerts are always preserved; informational queries are dropped first.
Layer 5: Zero-Token Pipelines
For deterministic tasks, bypass the LLM entirely. Schedule pipelines via launchd/cron:
launchd β python3 pipeline.py β ctx_execute β ctx_deliver β iMessage/Telegram
No agent. No model. No tokens.
Savings benchmark
Measured on a live OpenClaw instance running 8 positions, 20-symbol movers, daily briefs:
| Call | Raw Output | After Filtering | Savings |
|---|---|---|---|
account | 357 B | 95 B | 73.4% |
positions (8 holdings) | 2,739 B | 822 B | 70.0% |
movers (20 symbols) | 2,284 B | 367 B | 83.9% |
| Pipeline total | 5,380 B | 1,284 B | 76.1% |
Across all measured workloads, savings sit in the 70-98% range β the upper end driven by analyses that would otherwise require pulling whole files (Read Γ N) versus a single ctx_execute that emits only the answer.
Zero-token morning brief pipeline: launchd triggers Python directly β no LLM tokens consumed.
Before & After
WITHOUT Context Saver:
agent calls skill β 3 KB raw JSON floods context β 40 wasted fields
agent calls skill β 5 KB raw JSON floods context β 50 irrelevant records
agent calls skill β 20 KB raw JSON floods context β 200 search results
Session compacts β all working state lost β 20 KB cold restart
Daily token burn: ~750,000 tokens
WITH Context Saver v4.6:
agent calls ctx_execute β 120 B summary enters context β full data indexed
agent calls ctx_execute β 300 B filtered enters context β only matching records
agent calls ctx_batch β 500 B combined β one MCP call, not three
Session compacts β 2 KB snapshot preserved β instant resume
Daily token burn: ~200,000 tokens (73% reduction)
Security
All code is audited and hardened:
- Sandboxed execution β Subprocess isolation with env var denylist (30+ dangerous vars), process group kills on Unix, 100 MB output cap.
- Exit classification β v4.6 distinguishes timeouts, language-missing, and sandbox blocks from generic runtime errors so agents can react appropriately.
- No
shell=Trueβ All subprocess calls use list-based args (shell=False). - Secret redaction β API keys, Bearer tokens, Stripe/Alpaca prefixes, and long base64 strings stripped before FTS5 indexing.
- Path traversal protection β Skill names validated with
^[a-zA-Z0-9][a-zA-Z0-9_-]*$. - Index size caps β 100 KB per entry, 10 K max rows with automatic pruning.
- Parameterized SQL β Zero SQL injection vectors.
- Snapshot budget clamped β 256-65536 byte range enforced.
- Phone validation β E.164 format enforced for iMessage delivery.
- Atomic config writes β adapters write
tmp + renameso a crashed install never leaves a half-written~/.cursor/mcp.json. - No outbound network calls in the upgrade reminder β purely a local timestamp comparison.
- No third-party runtime dependencies β
@modelcontextprotocol/sdk,better-sqlite3,turndown,zod. Nothing else.
Environment Variables
| Variable | Default | Description |
|---|---|---|
OPENCLAW_HOME | ~/.openclaw | Root directory for OpenClaw |
CTX_SNAPSHOT_BUDGET | 2048 | Max bytes for session snapshots (256-65536) |
CTX_FTS_ENABLED | 1 | Set to 0 to disable FTS5 indexing |
TELEGRAM_BOT_TOKEN | β | Telegram bot token for ctx_deliver |
TELEGRAM_CHAT_ID | β | Default Telegram chat ID |
SLACK_WEBHOOK_URL | β | Slack incoming webhook URL |
DISCORD_WEBHOOK_URL | β | Discord webhook URL |
Project Structure
context-cooler/
βββ src/
β βββ server.ts # MCP server entry point (stdio transport)
β βββ tools/
β β βββ execute.ts # ctx_execute β sandboxed execution + status
β β βββ execute-file.ts # ctx_execute_file β file-aware execution
β β βββ batch.ts # ctx_batch β multi-command pipeline
β β βββ search.ts # ctx_search β FTS5 knowledge query
β β βββ index.ts # ctx_index β content indexing
β β βββ fetch-index.ts # ctx_fetch_index β HTTP fetch + index
β β βββ session.ts # ctx_session β P1-P4 session continuity
β β βββ stats.ts # ctx_stats β usage aggregation
β β βββ deliver.ts # ctx_deliver β multi-messenger delivery
β β βββ doctor.ts # ctx_doctor β health check + upgrade reminder
β βββ lib/
β β βββ sandbox.ts # Subprocess runner (11 languages)
β β βββ exit-classify.ts# v4.6 β status classifier
β β βββ filter.ts # Intent-driven keyword scoring
β β βββ db.ts # SQLite + FTS5 connection management
β β βββ chunker.ts # Markdown/JSON/text chunking
β β βββ redact.ts # Secret redaction patterns
β β βββ env.ts # Environment and config loader
β βββ adapters/ # v4.6 β platform installers (β€80 lines each)
β βββ claude-code.ts
β βββ cursor.ts
β βββ codex.ts
β βββ gemini.ts
β βββ opencode.ts
β βββ types.ts
β βββ util.ts # atomic write, JSON read, splice helpers
β βββ index.ts # CLI entry point + registry
βββ install.py # Cross-platform installer (interactive in v4.6)
βββ package.json # Node.js dependencies
βββ tsconfig.json # TypeScript configuration
βββ skill.json # MCP server manifest
βββ docs/
βββ ARCHITECTURE.md # Detailed architecture documentation
License
MIT
