# LLMSlim + Claude Code

> Run Claude Code through a local proxy that shrinks long tool output once and resends the same bytes every turn, so prompt caching and thinking keep working.

Claude Code resends the whole conversation on every turn, so a long test log or search result is paid for again and again and fills the context window until Claude Code compacts. llmslim wrap claude starts a local proxy and runs Claude Code through it. The first time the model is about to see a long shell, search or web result, LLMSlim shortens it, keeping errors, failures and the lines related to the command. It stores that version and sends exactly the same bytes on every later request, so nothing the model has already seen ever changes. File reads and edits are never touched.

Category: Local & Edge

## Install

```bash
pip install "llmslim[proxy]"   # llmslim 0.11.0 or newer
```

No model is called and nothing new leaves your machine: Claude Code sends the same requests it always did, only shorter. Your API key or Claude login is forwarded to Anthropic as usual and never stored.

Run Claude Code through the proxy, then see what it saved:

```bash
llmslim wrap claude
llmslim proxy stats
```

## How it fits

- llmslim wrap claude starts the proxy on a free localhost port and runs Claude Code with ANTHROPIC_BASE_URL pointing at it. Every request is forwarded to Anthropic with its headers; responses stream back untouched.
- Tool output the model has not seen yet (everything after its last turn) from Bash, PowerShell, Grep, Glob, WebFetch, WebSearch or Monitor, over 1,500 tokens, is shortened once: errors and the lines related to the command stay, runs of similar lines collapse into one line and a count, and JSON lists keep every item.
- The decision is stored under the tool call id and the text. Whenever Claude Code resends that output, the stored text goes out instead, byte for byte, so the cached prefix and Claude's thinking signatures stay valid.
- Read, Edit and Write output, unknown tools and anything seen before the proxy started are never changed. MCP tools are opt-in, because some return live state such as a browser snapshot.

## Example

```bash
llmslim wrap claude -- -p "Run the tests and tell me what fails"
```

What Claude receives for a 10,545-token pytest log (156 tokens):

```text
[LLMSlim shortened this tool output from 10,545 to about 117 tokens, keeping errors and the lines most related to the call. Run a narrower command to see more.]
tests/test_api.py::test_endpoint_0 PASSED [0%]
... [410 similar lines]
tests/test_api.py::test_endpoint_411 PASSED [68%]
tests/billing/test_refund.py::test_rounding_half_even FAILED - AssertionError: Decimal('10.05') != Decimal('10.04')
tests/test_api.py::test_endpoint_412 PASSED [68%]
... [286 similar lines]
tests/test_api.py::test_endpoint_699 PASSED [116%]
=== 1 failed, 700 passed in 41.27s ===
```

The failing test, its assertion and the summary line stay; 698 passing lines collapse into two counts. If the model needs more, it can run a narrower command.

## Options

| Option | Default | Meaning |
|---|---|---|
| `--min-tokens` | `1500` | Leave output at or below this many tokens alone. |
| `--keep-ratio` | `0.35` | Fraction of a long output to keep (never below --min-keep, 1000 tokens). |
| `--tool / --never` | `` | Add a tool to compress, or exempt one. Repeatable. |
| `--mcp` | `off` | Also compress every MCP tool's output. |
| `--json` | `off` | Also compress JSON output. Off by default: agents given shortened JSON spent extra turns fetching the fields that were cut. |

## Deployment

Install llmslim[proxy] in any Python 3.9+ environment and start Claude Code with llmslim wrap claude instead of claude. Keep ~/.llmslim/proxy.db for as long as a session lasts: it holds the bytes the proxy replays. llmslim proxy stats shows the tokens it kept out of your requests.

## Tips

- Leave the defaults on first: they only touch long shell, search and web output, and leave JSON alone.
- It pays off most on long logs whose useful line isn't at the end: CI runs, linters, builds. For test runs agents already trim the output themselves.
- Exempt a tool with --never if you rely on its exact output, for example a custom script whose output you copy from.
- Opt data-only MCP tools in one by one, for example --tool mcp__github__list_issues.

## Limitations

- Claude Code already saves output over about 30 KB to a file and shows the model a 2 KB preview; the proxy works on the output that reaches the model in full, plus web results and the MCP tools you opt in.
- Anthropic Messages API only for now; Codex and other OpenAI-format agents are planned.
- With a custom base URL, Claude Code turns off Remote Control. It also turns off tool search, which adds about 7,100 tokens to every request; llmslim wrap claude turns it back on (ENABLE_TOOL_SEARCH=true) since 0.11.1, and you should set it yourself if you run llmslim proxy on its own.
- Through a proxy, claude -p starts in auto permission mode instead of default. Since 0.11.1, llmslim wrap claude starts print-mode runs in default mode unless you choose one.
- With a custom base URL, Claude Code skips a Team or Enterprise organization's server-managed settings. Don't use the proxy where those settings must apply.
- On real sessions, tool output is a small part of a Claude Code bill: in 444 real sessions, if all shell, search and web output had cost nothing, the bill would have been 13.8% lower. Re-reading long context is the bigger cost; Claude Code's /autocompact setting controls it.

## Evidence

| Metric | Uncompressed | Compressed | Impact |
|---|---|---|---|
| Failing CI run, about 12 KB of log (real Claude Code, Haiku 5.5, 10 runs per arm) | $0.0061 billed per run | $0.0041 | 32% cheaper, every run fixed the cause |
| Lint run: 3 errors among about 260 warnings | $0.0056 | $0.0045 | 21% cheaper |
| Fix a failing test, running pytest -v | $0.0036 | $0.0035 | Within noise: the agent already trims test output with tail |
| Pooled over 8 tasks, 0.11.0 settings |  |  | -5% to +5%. Shortened JSON cost about twice as much on one task, so it is off by default since 0.11.1 |
| Final request of an agent loop with thinking | Original output resent: HTTP 400 | Proxy's version resent: HTTP 200 | Thinking is bound to what the model saw; the replay keeps it valid |

## FAQ

### How much will it save me?

It depends on what your agent reads. In our published benchmark of real Claude Code (572 runs, billed dollars with cache reads priced separately), a failing CI log cost 26-32% less and a long lint run 17-21% less, while test runs changed little because the agent already trims them. Pooled over 8 tasks the change was between -5% and +5%. Run llmslim proxy stats after a session to see what it kept out of your requests.

### Does it break prompt caching?

No. Nothing the model has already seen changes: each shortened output is replayed byte for byte, so the cached prefix stays the same. In our run on Claude Haiku 5.5, cache reads grew on every turn.

### Does it break Claude's thinking?

No, that is what the replay is for. Thinking blocks are bound to everything before them; sending the original output instead of the version the model saw gets the request rejected with HTTP 400, which we reproduced. The proxy always resends the version the model saw.

### Does it work with a Claude subscription?

It should. Claude Code's gateway docs say a saved claude.ai login is sent through a custom base URL, and the proxy forwards every header to Anthropic unchanged and never stores credentials. Our own runs used an API key; tell us if your login behaves differently.

## Troubleshooting

- **claude was not found on PATH:** Install Claude Code first, or run the proxy yourself with llmslim proxy and point ANTHROPIC_BASE_URL at it.
- **A 400 about thinking after deleting ~/.llmslim/proxy.db mid-session:** The proxy can no longer replay what the model saw. Claude Code strips the old thinking and retries; start a new session to avoid it.

## Further reading

- [Proxy guide on GitHub](https://github.com/Thanatos9404/llmslim/blob/main/docs/PROXY.md)
- [Source: llmslim/proxy](https://github.com/Thanatos9404/llmslim/tree/main/llmslim/proxy)
- [Claude Code LLM gateway docs](https://code.claude.com/docs/en/llm-gateway-protocol)

Canonical page: https://www.llmslim.app/integrations/claude-code