Context Gateway: background history compaction for Claude Code and Cursor

What Context Gateway actually solves for coding agents

Long agent sessions hit a context limit, and the usual fix is to summarize the older turns. The problem is timing. If the summarization call runs when the limit is reached, the user waits for it. Context Gateway moves that work off the critical path: it sits between the agent and the LLM API, watches the conversation length, and starts compressing history in the background before the limit is reached. The README frames the result as "No more waiting" when a conversation hits context limits, because the summary was pre-computed.

The audience is narrow and specific. The README lists claude_code, cursor and openclaw as supported agents, plus a custom option. That is a tool for developers running one of those agents locally and willing to insert a proxy process between the editor and the model provider. It is not a library you call from your own application, and it is not a retrieval layer. Nothing in the repository suggests it stores or searches documents.

How the proxy, the trigger threshold and the background summarizer fit together

The architecture is a man-in-the-middle process. The agent sends its normal API requests to the gateway, the gateway forwards them upstream, and it inspects the conversation as it passes. The go.mod file shows the pieces this requires: tidwall/gjson and tidwall/sjson for reading and rewriting JSON fields without deserializing the whole payload, pkoukk/tiktoken-go for token counting, coder/websocket for streaming connections, and modernc.org/sqlite for local storage.

Compression is governed by a trigger threshold, described in the README as defaulting to 75%. When the conversation crosses that share of the context window, the gateway starts a summarization call in the background rather than waiting for the agent to be blocked. The summarizer is a separate model with its own API key, configured through the TUI wizard. That is the key design split: the agent talks to one provider, the summarizer talks to another, and the gateway owns the boundary between them.

The observability story is a JSONL file. The README points readers at logs/history_compaction.jsonl to see what is happening. A line-oriented log is a reasonable choice for a proxy, since it is easy to tail and easy to parse, but it also means the gateway's own state is not queryable through an API. There is a web dashboard in the repository (the Makefile builds a React app from web/dashboard into cmd/dashboard_dist/ and embeds it in the binary), and the Dockerfile exposes port 18081, so the dashboard is reachable over HTTP in the container. The README does not describe what the dashboard shows.

Installing Context Gateway and running your first compacted session

The README gives a two-step install. The first command downloads and installs the gateway binary from the vendor's install endpoint. The second launches the binary with no arguments, which the README says opens an interactive TUI wizard.

curl -fsSL https://compresr.ai/api/install | sh
context-gateway

Running context-gateway with no subcommand is the configuration path, not the serving path. The wizard asks you to choose an agent (claude_code, cursor, openclaw or custom), then walks through the summarizer model and its API key, an optional Slack notification toggle, and the trigger threshold for compression. The README states the default threshold is 75%.

The environment file in the repository shows which credentials the gateway expects. Copy .env.example and fill in the keys you actually use; the summarizer path depends on COMPRESR_API_KEY and COMPRESR_BASE_URL, while the agent's own provider key is separate.

cp .env.example .env
# COMPRESR_BASE_URL=https://api.compresr.ai
# COMPRESR_API_KEY=your_compresr_api_key_here
# ANTHROPIC_API_KEY=your_anthropic_api_key_here

If you prefer containers, the Dockerfile builds the binary with CGO disabled, runs it as a non-root gateway user, and exposes port 18081. The container's entrypoint is the gateway binary with the arguments serve --no-banner, so the container starts the server directly rather than the wizard.

FROM alpine:3.21
WORKDIR /app
COPY --from=builder /build/gateway .
RUN mkdir -p /app/logs && chown -R gateway:gateway /app
USER gateway
EXPOSE 18081
ENTRYPOINT ["./gateway"]
CMD ["serve", "--no-banner"]

After a session, the README says to check logs/history_compaction.jsonl for what happened. That file is the first thing to look at when compaction does not fire: it is the only documented record of the gateway's decisions.

Where Context Gateway is the wrong tool

The gateway compresses history. It does not decide what history is worth keeping in a semantic sense, and it does not retrieve anything from outside the conversation. If your problem is that the agent cannot see the right files or the right past decisions, a summarizer in front of the API will not fix it. A retrieval layer or a memory store addresses that class of problem; this proxy does not.

The second boundary is provider coupling. The summarizer is a hosted service with its own API key and base URL, and the .env.example also lists QWEN_CODER_API_KEY, SWE_PRUNER_BASE_URL and per-provider keys for Anthropic, OpenAI, Gemini and Cursor. The repository does not document a fully local summarizer path, so a team that cannot send conversation content to an external summarization endpoint has no configuration described here that would satisfy that constraint. That is a deployment blocker, not a tuning problem.

The third is operational. A proxy in the request path is a new failure domain. If the gateway process stops, the agent's requests stop with it. The README does not document a fallback mode, a passthrough-on-error behaviour, or rollback steps for a bad compaction. The logs/history_compaction.jsonl file tells you what happened after the fact; it does not tell you what the gateway does when the summarizer call fails mid-session. Treat that as unknown until you read the code in cmd/ and internal/.

How this differs from running a summarization middleware yourself

A common alternative is to write your own middleware in front of the provider API: intercept the request, count tokens, and call a summarization model when a threshold is crossed. The difference is where the summarization runs relative to the request. A naive middleware summarizes synchronously, so the user waits. Context Gateway's stated design is to pre-compute the summary in the background, which means it must hold state about the conversation between requests and predict when the threshold will be crossed, not just detect that it has been.

That is a harder problem, and it is why the repository carries a SQLite dependency and a token-counting library rather than being a thin HTTP handler. It also explains the agent-specific configuration: claude_code, cursor and openclaw each have their own request shapes, and a generic middleware would need to handle all of them. The trade-off is that a hand-written middleware can be adapted to any provider in an afternoon, while Context Gateway supports the agents it lists and a custom option whose scope the README does not define.

If your agent is not one of the supported ones and you do not want to reverse-engineer the custom configuration, a synchronous summarizer you control is the more predictable path, even though it costs the user a wait.

Maintenance, build requirements and licence

The repository is not archived, and the last push was on 2026-08-02. The most recent tagged release listed is v0.5.3 from 2026-03-18, with v0.5.2 and v0.5.1 earlier in March. That gap between the last push and the last tag is worth noting: activity on the default branch has continued past the release line, so building from source gives you code that is not in v0.5.3.

Building from source is not a single go build. The Makefile's build target depends on embed-prep and build-dashboard, and build-dashboard runs npm run build inside web/dashboard before the Go binary is compiled, because the dashboard assets are embedded. You need Go 1.24.0 or later (the go.mod directive) and a Node toolchain. The Dockerfile takes the same route, running make embed-prep before compiling with CGO_ENABLED=0.

Upgrade cost is mostly configuration drift. The wizard writes the config, and the README does not describe a migration path between versions or a schema version field. The Makefile references several config files under configs/ (preemptive_summarization.yaml, tool_output_passthrough.yaml, config.yaml), which suggests the config surface has grown across releases. Check ChangeLog.md before upgrading, since it is the only changelog in the repository listing.

The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant. It also requires that you preserve copyright and licence notices and state significant changes. That is the standard Apache-2.0 obligation, not legal advice; if you plan to redistribute a modified gateway, have counsel review the NOTICE requirements.

Editorial conclusion

Adopt Context Gateway if you run Claude Code, Cursor or openclaw sessions that regularly hit context limits and you are willing to route traffic through a local proxy and configure a summarizer API key. Skip it if you need retrieval, long-term memory or a hosted service, because the repository describes none of those. Before installing, read cmd/ and internal/ to confirm which endpoints the proxy actually intercepts, and check docs/ for the config schema, since the README does not document failure handling or rollback.

Frequently asked questions

Official sources

1. Compresr-ai/Context-Gateway on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases