CacheLane

3. The trick: mark the cache boundaries (without moving anything)

CacheLane classifies each request into three volatility regions and places two cache_control breakpoints at the boundaries. It does not reorder your conversation: the API already sends system and tools before messages, and new turns append to the end, so the stable material is naturally at the front. CacheLane only marks where the cache boundaries sit (and strips/replaces any breakpoints Claude Code already set):

+----------------------------------------+
| STABLE    system prompt, tool schemas, |  identical every turn
|           CLAUDE.md, pinned rules      |  -> billed at 0.1x
| ============ cache breakpoint ======== |
| SEMI      recent turns + files read    |
| ============ cache breakpoint ======== |
| VOLATILE  your newest message + latest |  the only genuinely new part
|           tool output                  |  -> full price, but small
+----------------------------------------+

The expensive stable block sits at the front of every request by API structure and stays byte-identical, so the breakpoint lets Anthropic serve it from cache cheaply. The volatile material is already at the back — where its churn can't invalidate anything above it — so CacheLane never has to move it. Only the small new piece at the bottom pays full price.

4. Worked example: "read a file"

Say the unchanging stuff (system + tools + the file) is 15,000 tokens, and each new message is 500 tokens.

| Turn | What happens | Cost (token-units) | |------|--------------|--------------------| | 1 (read file X) | Nothing cached yet; the stable block is written to cache at 1.25× | 15,000×1.25 + 500 ≈ 19,250 | | 2 (explain foo) | Stable block is now a cache hit at 0.1× | 15,000×0.1 + 500 ≈ 2,000 | | 3, 4, 5 … | Same cheap path every turn | ≈ 2,000 each |

Per-turn cost collapses after the first turn:

cost/turn
 19k | #                              turn 1: pay once to seed the cache
     |
 10k |
     |
  2k |   #  #  #  #  #  #  #  #  #     every turn after: flat and cheap
     +-------------------------------
       1  2  3  4  5  6  7  8  9 ...

> "Read that file again"? It's already in the cached front, so it costs 0.1×, basically free. You never re-pay full price for it.

5. Why the savings grow with session length (the math)

Let S = the size of the repeated part of your prompt (system + tools + files already read), the part CacheLane keeps stable. Over N turns, what do you pay for that part?

Without caching:   N x S            (full 1x price, every turn)

With CacheLane:    1.25 * S         (write it once, on turn 1)
                 + (N - 1) * 0.1*S  (cheap 0.1x read, every turn after)

Divide the CacheLane cost by N to get the average per-turn cost (per unit of S):

  1.25*S + (N - 1)*0.1*S                  1.15
  ----------------------- =  ( 0.1  +  -------- ) * S
            N                              N

That single formula is the whole story (the multipliers 1.25 and 0.1 are the cited Anthropic rates above):

| Turns N | avg per-turn cost | savings vs. full price | |-----------|-------------------|------------------------| | 1 | 1.25× | (just the write) | | 2 | 0.675× | ~32% | | 10 | 0.215× | ~78% | | 50 | 0.123× | ~88% | | large N | 0.1× | 90% (the ceiling) |

As the session grows, the one-time 1.15/N write cost shrinks toward zero and the average slides down to 0.1×, i.e. a 90% discount on the repeated part. That 90% is not a marketing number. It is exactly the cache-read multiplier (0.1×) from the table above, and it is the theoretical ceiling. Real sessions also carry a small always-full-price "new" part each turn plus the occasional cache miss, which pulls the measured number down to roughly 80%, which is what cachelane stats reports in practice. Short chats sit low on this curve; long coding sessions ride near the top.

6. Keeping it lean: K-pruning and stubs

Caching makes the prompt cheap, but a long session still makes it big. Old tool outputs and file dumps pile up after they stop being relevant. So CacheLane tracks how many turns each block goes untouched, and once a block has been idle for K turns (default K = 3) it swaps the full content for a tiny stub:

Claude Code sends:   [ ...history... ][ 5,000-token file ][ new msg ]
                                        |  idle for K turns
                                        v  CacheLane substitutes (forwarded copy only)
Anthropic receives:  [ ...history... ][ stub: id + summary + expand() ][ new msg ]

K-pruning is lossless and metadata-only. Claude Code still holds the original and re-sends it every turn; CacheLane just masks it in the copy forwarded to Anthropic. If the model needs it back, it calls the cachelane_expand MCP tool, CacheLane flips that block from "stub" to "live", and the real content flows through again on the next turn. (Expanding is far cheaper than re-reading the file from scratch: the call carries just a block id, and it re-uses the existing cache entry instead of paying a fresh 1× read plus a 1.25× cache write for newly-read content.)

7. Why there's a database

Placing breakpoints on one request needs no memory, but pruning and restoring are stateful across turns. So CacheLane keeps a local SQLite database (~/.cachelane/cachelane.db) holding metadata:

• Idle counters: "this block has been untouched for 3 turns" is impossible to know without history.
• Stub state and refetch handles: which blocks are currently masked, and how cachelane_expand puts them back.
• Prefix hashes: to confirm the stable region really stayed byte-identical (so the cache will hit) and to detect drift.
• Keepalive state: which sessions are idle and how big their prefix is.
• Stats: token counts, hit ratios, and savings that power cachelane stats, sessions, and explain.
• Optional retained originals: only when compression.retention.enabled is explicitly enabled, CacheLane may store original tool outputs locally so Claude can retrieve them through cachelane_retrieve_tool_output.

By default CacheLane does not store prompts, code, or tool-output bodies. Enabling compression retention changes that privacy posture for tool outputs only; retained originals are scoped to the local workspace/session and expire according to compression.retention.ttl_days.

8. Keeping the cache warm (keepalive)

Anthropic's cache lives about 5 minutes by default; a 1-hour tier is available at 2× write cost (Prompt caching). If you step away mid-session, the cache would expire and your next turn would pay full price to re-seed it. So a keepalive worker sends a minimal synthetic ping (max_tokens=1) during idle gaps to keep the prefix hot, and CacheLane promotes large prefixes (≥ 50k tokens) to that 1-hour tier automatically.

How it works

cachelane install makes two edits to your Claude Code configuration:

1. Registers an MCP server in ~/.claude.json (mcpServers.cachelane). Claude Code launches cachelane mcp automatically every time it starts.
2. Redirects API traffic by setting ANTHROPIC_BASE_URL=http://127.0.0.1:7332 in ~/.claude/settings.json. This is what routes Claude Code's requests through CacheLane.

The cachelane mcp process does two jobs in one process:

• Exposes MCP tools to Claude (cachelane_stats, cachelane_explain, cachelane_expand, cachelane_health).
• Because auto_proxy is on by default, it also starts the HTTP proxy on 127.0.0.1:7332 in the same process.

So a single auto-launched process owns everything. That's why you never start anything by hand, and why running cachelane proxy separately would fight it for the port.

For each turn the proxy:

1. Intercepts the outgoing request from Claude Code.
2. Runs the pipeline (compress tool outputs → classify → prune → place cache_control breakpoints) — measured at **

Sessions are keyed by Claude Code's own session id, so the value in the `cachelane sessions` table is exactly what `--session-id` expects.

### Per-block cost attribution (`explain --top-blocks`)

`cachelane stats` shows aggregate savings, but it doesn't tell you *which blocks* are eating your budget. The `--top-blocks` flag on `explain` breaks that down:

```bash
cachelane explain --top-blocks        # top 10 blocks by token weight (default)
cachelane explain --top-blocks 5      # top 5
cachelane explain --turn 3 --top-blocks 20   # specific turn, top 20

Sample output:

Turn 42 — Top blocks by token weight

  Block ID                                Kind            Region      Tokens  Tier              Est. Cost
  ──────────────────────────────────────────────────────────────────────────────────────────────────
  block-2-file1                           file_read       STABLE       15000  cache_read        1500.0 cu
  block-3-file2                           file_read       SEMI          8500  cache_creation_5m  10625.0 cu
  block-6-tool2                           tool_output     VOLATILE      4500  input (1x)        4500.0 cu
  block-1-system                          system_prompt   STABLE        4000  cache_read        400.0 cu
  block-4-tool                            tool_output     SEMI          3200  cache_creation_5m  4000.0 cu
  block-5-user                            user_message    VOLATILE        50  input (1x)        50.0 cu

  Region totals:
    STABLE  :    19000 tokens → cache_read         (0.1x)     →  1900.0 cu
    SEMI    :    11700 tokens → cache_creation_5m  (1.25x/2x) → 14625.0 cu
    VOLATILE:     4550 tokens → input              (1x)       →  4550.0 cu
    Total effective: 21075.0 cu  (vs. 35250.0 baseline — 40.2% savings)

Each block shows:

• Region: which volatility bucket (STABLE / SEMI / VOLATILE) the block landed in.
• Tier: the actual billing tier from the API response — cache_read (0.1×), cache_creation_5m (1.25×), cache_creation_1h (2×), or input (1×).
• Est. Cost: token coun

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Aditya-Tripuraneni
• Source: Aditya-Tripuraneni/CacheLane
• License: Apache-2.0
• Homepage: https://cache-lane.vercel.app/

Install and usage instructions live in the source repository linked above.