Coding agent plugin · v0.5.40

One install. Every coding agent. Fewer tokens.

Run supercompress setup once. It links your account, detects coding agents, and installs a clean MCP + hooks plugin across your coding agents: Cursor, Claude Code, Codex, Goose, Zed, OpenCode, fx, Hermes, OpenClaw, and more. Keep your normal login. Check health anytime with supercompress doctor.

Install in 30 seconds

npm install -g supercompress-proxy
supercompress setup
supercompress doctor

setup links your account and wires MCP + hooks on every detected host. Re-run supercompress plugin anytime. doctor prints a clean per-agent health matrix.

query-awarekeeps the context that answers your question

hostedquery-aware compression API

extractiveoriginal lines kept verbatim

First 5 minutes checklist

Get SuperCompress running with your coding agents in 4 quick copy-paste steps:

Install & link account

Install the CLI globally and run one-time setup to connect your account and auto-configure detected agents:

npm install -g supercompress-proxy
supercompress setup

Verify agent detection

Confirm which coding agents on your machine were detected and hooked:

supercompress agents

Test MCP connectivity

Verify that the SuperCompress MCP server is responsive locally:

supercompress mcp-check

Restart agent & compress

Restart Cursor, Claude Code, Codex, Roo Code, or Cline so the MCP server initializes. Your agent will now automatically call compress_context on bulky context dumps!

How it works

Two layers, installed together by setup:

Hooks (Cursor / Claude Code / Codex), every user message + large tool dumps auto-compress.
MCP on every detected agent, compress_context for big dumps (subscription / login safe).

# After `supercompress setup` (subscription / login safe)
Coding agent ──→ hooks / compress_context ──→ SuperCompress API

Auth Laptop setup uses browser device-link (Google). Hosted MCP at /api/mcp accepts an sc_ API key header. OAuth 2.1 + PKCE is how a keyless Google sign-in path is designed; it is not the recommended install today. Context is compressed on the SuperCompress API; provider keys never leave your agent.

Install

npm install -g supercompress-proxy
supercompress --version
# → 0.5.40

Or one-shot without a global install:

npm install supercompress-proxy
npm exec supercompress setup

Detect + plugin

setup links your account and installs the MCP plugin. Prefer plugin anytime you add a new agent:

supercompress setup
supercompress plugin

$ supercompress plugin
✓ Detected Cursor, Claude Code, Codex, FreeBuff, OpenCode, …
✓ MCP plugin installed for: Cursor, FreeBuff, OpenCode, Codex MCP, …
✓ Cursor rule written
→ Works with login, no provider API-key mode
→ Restart your coding agent so MCP reloads

Install

Add supercompress-proxy with npm.

Link

supercompress setup opens the dashboard and connects your account.

Restart

Reload Cursor / Claude / Codex / FreeBuff / OpenCode so MCP servers load.

Compress

Ask the agent to compress large context, tool: compress_context.

Supported agents

Works across most coding-agent harnesses. The popular ones get a first-class auto MCP plugin from setup / plugin, native config shape per host, not a clunky one-size paste:

Cursor

~/.cursor/mcp.json + hooks + always-on rule.

MCP

Claude Code

~/.claude.json + hooks + CLAUDE.md.

MCP

Codex

~/.codex/config.toml MCP + hooks.

MCP

Goose

YAML extensions.supercompress stdio MCP.

MCP

OpenCode

mcp.supercompress in opencode.json(c).

MCP

Zed

context_servers.supercompress (native).

MCP

Grok / fx / Hermes / OpenClaw

Host-native MCP + instructions / skills.

MCP

Windsurf · Continue · Cline · Roo · Gemini · FreeBuff · Claude Desktop · …

Auto-written into each host’s MCP schema.

MCP

Also catalogued, supercompress agents connect or OpenAI/Anthropic base URL

AiderOpenHandsAmazon QJetBrains AITraeAntigravityAugmentWarpDevinCopilot CLIPiCrush+ more

Run supercompress agents for the full list on your machine. Health: supercompress doctor.

MCP tools

Tool	What it does
`compress_context`	Compress bulky coding context. Pass the user's question as `query` for the smallest digest; without one, dump mode keeps about half. Read any warning; a passthrough means keep your original text.
`connect_account`	Open the dashboard to link this install if you skipped setup.
`usage_summary`	Per-agent token savings for the connected SuperCompress account.
`runway_check`	Provider rate-limit runway for this agent (local plugin only, no account needed): `go`, `pace` (balanced policy only), `land`, `wait` or `unknown`.

On the hosted API and hosted MCP endpoint, query is optional. The local npm plugin (supercompress-proxy 0.5.40) still requires query until the next proxy release.

Rate-limit runway

supercompress limits (alias runway, or supercompress limits --json for agents) and the local MCP tool runway_check tell the agent how much provider quota is left and what to do with it: go (keep working), pace (balanced policy only), land (keep working, but commit or write a handoff note before each step), wait (the window is exhausted, retry after the reset) or unknown (no data source yet; a limit is never invented).

supercompress limits
supercompress limits --json
supercompress runway

Source	Harnesses
`~/.codex/sessions` rate-limit events (zero config)	Codex
Statusline tee, wired by `setup` or `supercompress limits connect claude-code` (your own statusline keeps working)	Claude Code
Rate-limit headers seen by the optional local proxy	Aider, Continue, Cline, OpenCode, Goose via `localhost:8080`
`supercompress limits ingest --provider <id>`	Cursor, Windsurf, Grok Build, Gemini CLI, custom hooks

setup and plugin wire Runway automatically and uninstall reverses it. Set SUPERCOMPRESS_RUNWAY=0 to opt out. Runway runs in the local plugin; the hosted MCP URL does not have it. Guide: check Codex and Claude Code rate limits from the terminal.

Dashboard tracking

After agents start compressing, your dashboard shows per-agent requests, tokens in/out/saved, and last-used time. Only usage metadata is sent, never prompt contents.

Optional API proxy

If you want the older base-URL rewrite path (provider API-key mode), opt in explicitly:

supercompress setup --proxy
supercompress start

That wires http://localhost:8080/v1 for compatible OpenAI/Anthropic endpoints. Most subscription/login agents should stay on the default MCP plugin path instead.

When to use --proxy Only when your agent already uses a provider API key and exposes a configurable OpenAI/Anthropic base URL. ChatGPT-login Codex and similar hosted backends are not intercepted by the local proxy, use MCP.

Uninstall

supercompress uninstall
npm uninstall -g supercompress-proxy

Uninstall removes only SuperCompress's own entries (MCP registrations, hooks, instructions, the runway statusline hook) and leaves everything else in your configs, including MCP servers you added after install, then cleans ~/.supercompress.

README badge

Using SuperCompress in a project? Add the badge to your README:

[![Compressed with SuperCompress](https://www.supercompress.dev/badge.svg)](https://docs.supercompress.dev/coding-agents)