Proxy

The local proxy is a reverse proxy on loopback. You point an existing coding agent or provider SDK at http://127.0.0.1:8787, it forwards each request to your chosen model API with the credential that came in, and it compresses eligible context before those bytes leave.

It is one of two things you install. The skill changes how an agent writes. The proxy changes how much the agent has to read. They run independently.

Repository

JuliusBrussee/caveman

Binary

caveman-proxy

Listen

127.0.0.1:8787

Account

Not required.

Licence

BSL 1.1, converting to Apache 2.0 after four years.

Reports

Always inferred. It cannot emit verified.

The agent and the provider request format stay as they are. The proxy is a base-URL swap, not a new agent loop. Recovery copies live in ~/.caveman/ccr.db on this machine. Usage rows live in ~/.caveman/caveman.db. Neither file is a bill.

Two ways in#

Wrap an agent. The CLI starts the proxy and points a known coding agent at it:

npm install -g @caveman-ai/cli
caveman setup --install
caveman claude

The same shortcut exists for Codex, Gemini CLI, Aider, Hermes, Kilo, OpenClaw, opencode, Pi, and Qwen Code. See Wrap an agent.

Start the listener yourself. Use this when an application already has a provider SDK and you only want to change its base URL:

caveman start

Default mode for a bare caveman start is record: every model-visible byte is forwarded unchanged, and the proxy writes local usage rows. Wrap defaults the other way, to compress. Modes explains the difference.

What happens to a request#

1. The agent sends a provider-shaped HTTP request to loopback.
2. The proxy matches a route, keeps or resolves the credential, and inspects the body.
3. If the mode allows it and every gate passes, the engine stores the original bytes and emits a smaller view plus a recovery handle.
4. The proxy forwards the (possibly smaller) request upstream and streams the provider response back.
5. A local usage row is written. Token reductions on that row are inferred.

If any transform gate fails, step 3 is skipped and the original body is forwarded. A compression problem never becomes a fake success or a client-side parse error. Provider errors still arrive as provider errors.

Build from source#

Most people never do this. The CLI installs a signed caveman-proxy into ~/.caveman/bin. If you want the binary yourself:

git clone https://github.com/JuliusBrussee/caveman
cd caveman
go build -o ./bin/caveman-proxy ./proxy/cmd/caveman-proxy
ANTHROPIC_API_KEY=… ./bin/caveman-proxy

There is no npm, pip, Docker, or Homebrew package for the proxy itself. @caveman-ai/cli is the MIT launcher.

What the numbers mean#

In a pinned Claude Code benchmark, the wrap path used 33.2 percent fewer provider-reported input tokens across 18 paired runs of six cases. The case-clustered 95 percent interval is 14.6 to 48.5 percent. All 18 exact-answer checks passed. One case regressed by 9.9 percent and stays in the aggregate. That is controlled benchmark evidence on a pinned agent build, not production traffic and not verified.

Local rows the proxy writes after your own sessions stay inferred. They are never multiplied into a monthly figure and never converted to money.

What it will not do#

It will not bind to a LAN, container bridge, or public interface. A non-loopback listen address is rejected, because the listener has no inbound authentication.

It will not log authorization headers, put API keys in YAML, or emit verified.

It will not replace your agent. Claude Code still owns its UI, permissions, and model calls. The proxy owns the hop between that agent and the provider.

It will not compress when the recovery store cannot accept the original. No store, no lossy transform.

Running it#

What it does to your bytes#