chore: context-efficiency — slim CLAUDE.md + cheaper HW captures#47
Merged
Conversation
…ure.md CLAUDE.md had grown to ~100 KB (~25K tokens) and is loaded into context on every turn of every session. The directory map + operating rules (Running, Configuration, Visual verification, Quirks) are what's needed turn-to-turn; the per-module deep-dives read like a design doc and are needed only when touching a specific module. Move the `### <module>` deep-dive subsections (api/audio/sampler/video/modes/ scenes/.../control_plane) into a new docs/architecture.md, read on demand. CLAUDE.md keeps the directory tree as a map plus a pointer to the companion doc. Net: CLAUDE.md ~99.5 KB -> ~30.5 KB, cutting the always-loaded per-turn baseline by ~17K tokens. Repo-relative links in the moved content are rewritten to ../-relative to match the other docs/ files.
…ad back) The Cam Link grabs 1080p, but the C64 active area is only 320x200 — a frame scaled to ~960px still resolves glyphs / per-cell colour / tearing while costing a fraction of the image tokens a full 1080p PNG does when an agent reads it back into context (the project's captures were the single largest category of big tool results). Add _diaglib.save_image(frame, path, max_width=DEFAULT_VERIFY_WIDTH) and route hdmi_capture.py through it: default 960px longest edge, --width to override, --full for native (pixel-peeking fine bottom-row glyph shimmer). New capture tools should write via save_image for the same default. Env override C64_DIAG_VERIFY_WIDTH; README + tool table updated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reduces per-turn context cost from analysis of this project's Claude Code session history (164 sessions, ~8.5B cache-read tokens).
Changes
1. Split per-module internals out of CLAUDE.md →
docs/architecture.mdCLAUDE.md is loaded into context on every turn of every session; it had grown to ~100 KB (~25K tokens). The directory map + operating rules stay; the per-module deep-dives (read like a design doc, needed only when touching a module) move to a read-on-demand companion. CLAUDE.md keeps the tree + a pointer.
../-relative to match otherdocs/files;[[memory-slug]]cross-links preserved.2. Downscale HW-verification captures before write
Cam Link grabs 1080p, but the C64 active area is 320×200 — a ~960px frame still resolves glyphs/colour/tearing at a fraction of the image tokens. Captures were the single largest category of big tool results in the session history.
_diaglib.save_image(frame, path, max_width=…);hdmi_capture.pydefaults to 960px,--widthto override,--fullfor native pixel-peeking. EnvC64_DIAG_VERIFY_WIDTH.Verification
ruff check/ruff format/pyright/unittestall pass (pre-commit gate).hdmi_capture.py --helpconfirms the new flags; docs/architecture.md links spot-checked to resolve.