wtf is image-context-cascade?

image-context-cascade solves a specific problem that shows up when using AI coding agents like Claude Code or Codex: every screenshot you paste into a conversation gets resent in full, as base64 text, on every single request after that, even many turns later. In one measured session, screenshots ate over 86 percent of the context window, and requests can grow so large the session simply breaks with an error. This tool fixes the problem before a request ever leaves your machine, by downgrading older images to small, stable placeholders while keeping the images from the current turn intact. It sorts images into three tiers: hot images from the current turn are sent as is, warm images from recent history can get optional thumbnails, and cold images from older history become tiny placeholders that can be restored later by their hash if needed. Nothing is ever permanently deleted, only archived, and only images are touched, so the actual text of a conversation stays unchanged. Measured results show a single 1.3 megabyte image shrinking to 315 characters, and in one real session, downgrading four historical images cut input tokens from over 91,000 down to under 2,000. A full 50 megabyte session was reduced to about 2 megabytes with one command. Setup differs slightly by which coding agent you use. Some agents with the right hooks get this handled automatically on every request, Claude Code archives images automatically when a session ends, Codex needs the agent to propose the action for approval, and any other agent can use a manual command line tool on its session file. The project has no runtime dependencies and works with Anthropic, OpenAI Chat, and OpenAI Responses style request formats. Known limits include that it only handles images and not general text, it only recognizes exact byte-identical images rather than resized copies, and images referenced only by remote URL rather than embedded data are not processed. The README does not state a license.