Claude Code re-injects the same long <system-reminder> blocks (CLAUDE.md
hints, task-tools reminders, the dynamic skills list, etc.) into the
FIRST user message on every turn. They're text, so they're not part of
the system+tools image we already cache — they hit the wire fresh every
turn. This rewrite renders any reminder block ≥ minReminderChars (1000
by default, matching legacy/python/proxy.py) to PNG images placed inside
the user message content array, just like the static slab.
Why: the system+tools image is the only cache_control breakpoint we're
allowed (Anthropic caps at 4 and Claude Code uses the others). Per-block
reminder images therefore carry NO cache_control — they're per-turn
content that the model OCRs without prefix-cache benefit. The win is
token cost, not cache: reminders are 65-73% cheaper as PNG than as text,
and a typical turn has 1-3 of them.
Layout inside the first user message after compression:
[intro text] ← static (helps OCR framing)
[image block(s)] ← static; LAST has cache_control
↑ cache breakpoint (the only one)
[End of rendered context.] ← static text closer for the image
[processed existing content] ← per-turn (incl. reminder images)
Wire-up:
- src/core/transform.ts: new TransformOptions.compressReminders (default
true) + minReminderChars (default 1000). Two new helpers,
textToImageBlocks() (wraps renderTextToPngs + makeImageBlock with
no cache_control) and approxBlockBytes() (b64 → byte-count for the
imageBytes telemetry, no second base64 round-trip). The placement
='user' branch now walks `existing` and rewrites long reminders.
- src/core/tracker.ts: TrackEvent.reminder_imgs flows from
TransformInfo.reminderImgs through toTrackEvent so `pixelpipe stats`
and the dashboard can attribute compression contributions.
- src/worker.ts: COMPRESS_REMINDERS + MIN_REMINDER_CHARS env vars.
- src/node.ts: matching CliOpts, parseCli cases (--no-reminders,
--min-reminder-chars), help text, env-var summary, and `rem+N` in
the per-request console line when reminder_imgs > 0.
Tests:
- "compresses long <system-reminder> blocks in the first user message"
confirms info.reminderImgs ≥ 1, the reminder text is gone from
user-content text blocks, the user's actual prompt survives, and the
new reminder image blocks carry NO cache_control.
- "leaves short <system-reminder> blocks alone (below minReminderChars)"
confirms info.reminderImgs is 0 and the reminder text passes through
as text.
Two protocol-correctness fixes that have to ship together.
1. **Default placement: 'system' → 'user'.** Anthropic's `system` field is
typed as `string | TextBlock[]` — image blocks there come back as
`400 system.N.type: Input should be 'text'`. Images must go into a
user-message content array.
2. **ttl='1h' on the image's cache_control.** Anthropic enforces the rule
"ttl='1h' must not come after ttl='5m'" in processing order
(tools → system → messages). Claude Code marks its own user-message
content with ttl='1h'; if we leave ttl unset it defaults to '5m', our
block lands first in processing order, and the request 400s the moment
Claude Code's own 1h breakpoint shows up later in the conversation.
The existing image-placement tests now look in messages[0].content instead
of out.system, and a new test pins the ttl='1h' invariant directly.
Reads ~/.pixelpipe/events.jsonl (or --file / PIXELPIPE_LOG) and prints
a one-screen summary of how the proxy is doing:
- request counts by status bucket (2xx/4xx/5xx)
- compression rate (compressed vs passthrough)
- latency p50/p95/p99 (duration + first-byte separately)
- aggregate Anthropic token usage (input/output/cache_create/cache_read)
- cache hit rate computed two ways (by tokens, by events)
- top skip reasons (so we see WHY a request wasn't compressed)
- top cwds with per-project compression ratio
- system_sha8 distribution → 'reuse rate' = how often the cached
payload is being re-sent. High reuse + low cache_read means
something is breaking cache_control.
- unknown_static_tags warning section if Claude Code shipped a new
dynamic tag that we're silently baking into the image.
--json mode dumps the raw Summary as JSON for downstream pipelines.
Streaming reader so a 100 MB log file doesn't OOM. Pure aggregator
(fold/newSummary/renderTextReport) is unit-tested; only the file IO
shell is untested.
Dispatched from src/node.ts BEFORE parseCli so its flags don't collide
with the proxy's flags. The CLI shim in bin/cli.js stays unchanged.
Tests: +6 (status bucketing, compressed/passthrough split, token agg,
cwd & sha histogram, unknown-tag collection, text report rendering).
Node host now appends one JSONL event per request to
~/.pixelpipe/events.jsonl (override with --events-file or PIXELPIPE_LOG).
- Size-based rotation at 100 MB (old file → events.jsonl.1).
- Sync writes — overhead is ~1ms, dwarfed by upstream latency.
- Failures degrade silently: a broken disk disables the tracker but
never breaks a request.
- Flushed and fsync'd on SIGINT/SIGTERM so the last batch isn't lost.
- Opt out via --no-track or PIXELPIPE_TRACK=0.
Worker host uses JsonLogTracker with console.log; Cloudflare ingests
this as Workers Logs, and Logpush can ship it to R2/S3 as JSONL —
same shape Node writes locally, so analysis tooling works on either.
Console log line on both hosts now also includes tokens/cache_read
inline (e.g. 'compressed 4799ch → 2img/12343B tokens=1234+56
cache_read=800') so cache effectiveness is visible at a glance even
without parsing the JSONL.
Unknown-tag canary fires a stderr warning when info.unknownStaticTags
is non-empty — surfaces Claude Code releases that introduce new
dynamic tags before they tank the cache hit rate.
Help text and HANDOFF will be updated in the next commit; for now the
new flag drops the need for --exclude-dynamic-system-prompt-sections.
Tests: +5 (toTrackEvent flattening, JsonLogTracker sink behavior, error
swallowing, minimal-event handling, noop).
Two cheap guardrails based on architectural review:
1. Determinism test: renders the same input twice and asserts byte
equality of the produced PNGs. Without this guarantee, identical
system prompts on consecutive turns would yield different image
bytes, silently destroying the cache hit rate that justifies the
whole proxy. The test currently passes — locking it in so a future
refactor can't regress it without noticing.
2. Unknown-tag canary: splitStaticDynamic now sniffs the *static* slab
for any <tag>...</tag>-shaped block whose name isn't in
DYNAMIC_BLOCK_TAGS. Surfaced via info.unknownStaticTags and emitted
on the tracker event as unknown_static_tags. If Claude Code ships a
new per-turn tag in a future release, it'll show up in logs within
hours instead of being silently baked into the cached image (where
it would tank cache hit rate with no error).
Also adds tracker.ts (Tracker interface, TrackEvent shape,
JsonLogTracker, noopTracker, toTrackEvent normalizer). Hosts will wire
these in the next commit.
ProxyEvent gains two new fields:
- usage: Anthropic's input/output/cache_creation/cache_read tokens.
- firstByteMs: ms to upstream response headers (durationMs now measures
end-to-end since the event fires after usage is extracted).
Implementation (teeForUsage):
- Tee the response body. Client gets one side immediately; we read the
other in the background.
- SSE: scan up to 64 KiB for 'event: message_start' + the data: payload.
Usage is always in the first event so this terminates within ms of
upstream first byte.
- JSON: buffer up to 4 MiB and parse.
- Error responses (status >= 400) and bodyless responses skip extraction.
- Drains the tee fully in the background to avoid backpressure.
Without this, the proxy had no way to validate its own value
proposition. Now we can compute cache hit rate, real input-token
savings, etc. directly from log events.
Tests: +3 (JSON usage, SSE message_start usage, error skips extraction).
Three short hashes carried in TransformInfo:
- systemSha8: sha256[0..8] of the actual image-bound text. Stable
across turns proves cache_control is doing its job. If it drifts
unexpectedly, that's a cache leak to investigate.
- claudeMdSha8: hash of just the CLAUDE.md slab (heuristic header
detection). Lets us bucket requests by project even when cwd is
absent or anonymized.
- firstUserSha8: hash of first user message (4 KiB cap). Rough
thread id since the wire protocol has none.
All async via Web Crypto so Node + Workers share one impl. Hashing is
in parallel via Promise.all; ~0.1ms overhead.
+2 tests (systemSha8 invariant under dynamic-block change,
firstUserSha8 format).
New EnvFields type and extractEnvFields() helper. Parses the <env>
block Claude Code injects, plus 'On branch' / 'Branch:' lines that
appear in <git_status> or context blocks. Read-only — telemetry signal
only, never mutates the request.
Per-project compression ratios, repeat-CWD detection, today's-date
drift checks all become possible from logs now.
+2 tests (full env block extraction, no-env-no-info).
Claude Code injects per-turn blocks (<env>, <context>, <git_status>,
<directoryStructure>, <system-reminder>) into the system prompt.
Previously those got rendered into the image alongside the static
slab (CLAUDE.md, agent defs, tool docs), which kills Anthropic's
prompt cache: image bytes drift turn-to-turn → 0% cache hits.
Now we split:
- static (cacheable) → image with cache_control: ephemeral
- dynamic (per-turn) → plain text block AFTER the image
- billing line → also AFTER the image (was BEFORE, also a
cache-killer — bug fix as a side effect)
Net effect: stable cache key on the big slab, model still sees cwd /
branch / today's date. Removes the need for users to pass
--exclude-dynamic-system-prompt-sections to claude.
TransformInfo now carries staticChars / dynamicChars / dynamicBlockCount
for downstream telemetry.
Tests: 8 existing pass unchanged + 3 new (env survives as text after
image, cache_control on image only, all-dynamic input is pass-through).
teamchong