A single canonical document explaining how pixelpipe compresses Claude
Code requests end-to-end. Covers, in order:
1. Why this proxy exists
2. The static / dynamic split (DYNAMIC_BLOCK_TAGS, KNOWN_STATIC_TAGS)
3. What the final request looks like (placement='user' layout)
4. The cache_control budget (the one invariant that matters: ttl='1h')
5. Per-message compressions (reminders + tool_results, no cache_control)
6. Determinism and fingerprints (systemSha8, claudeMdSha8, firstUserSha8)
7. The unknown-tag canary
8. The savings math (effectiveCost / baselineCost from src/dashboard.ts)
9. What deliberately did NOT get built
10. Wiring map
Intended as the file a new contributor reads after CLAUDE.md but before
touching src/core/transform.ts. HANDOFF.md is session-state and rotates;
README.md is install/run; CLAUDE.md is rules; this is the architecture
reference that explains WHY the code looks the way it does.
Authored by the doc-writer teammate, KNOWN_STATIC_TAGS section
post-edited to reflect that e219b37 landed (not "future commit"). The
"source of truth" line in section 8 points at src/dashboard.ts directly
now that the Python reference has been removed (be372a0).
334 lines. No code changes; gates not re-run since this is doc-only.
teamchong