Re-reads re-pay.
The only way a model knows a file at turn 40 is that the file is literally present in the transcript at turn 40. Read a 500-line file ten times and you get ten copies, each billed and each diluting attention.
Stop paying for files your model already read.
GFC is an OpenCode plugin and MCP server. It treats the transcript the way git treats a working tree: the model gets a diff against what it last saw, never a full re-checkout.
MIT license. Zero dependencies. Zero tokens of per-turn overhead. Measured −22% to −34% context per turn.
Scroll to watch one file get read ten times.
The transcript is a linear replay.
Every turn re-sends the whole history. Here is what the usual fixes change, and what they don’t.
Caching cuts cost, not tokens.
Provider prompt caches lower the price of re-sent context. The tokens still flow, still compete for attention, and the cache breaks as soon as history changes mid-prefix.
Summarization is lossy.
Compaction throws away detail, and the model re-derives what was lost. That is waste plus repeated work.
GFC: exact, not approximate.
Not compression, but deduplication. A sha256 proves the bytes are identical, so the duplicate never enters the transcript at all. Nothing is summarized away. The content is verifiably still in context from the first read.
- read
- hash
- intercept
- delta
- scope
How it works.
One registry, one invariant. The filesystem is the store of truth. If the content on disk still hashes to the registered value, it is byte-identical to what the model already saw.
Hash every full read.
sha256 of file content, recorded per session in ~/.gfc/registry.json. Registry writes are atomic and cross-process locked, so parallel sessions can’t corrupt each other.
Intercept before the transcript.
The OpenCode plugin hooks tool.execute.after and replaces repeat content before it enters the message history. The duplicate never exists.
Return the delta.
Unchanged gives a ~70-token stub that cites the hash, including for unchanged pages of large files. Changed gives a numbered, multi-hunk diff from last-seen to current. Reads with offset or limit always return real lines, with a note if the file has drifted.
Scope to the session.
Models are stateless, so the first read in any session is always real content. No stub can hide something the model hasn’t seen. On compaction, summaries are told not to paste file contents, and GFC forgets the session, so the next read is real content again.
Try it.
One file, read the way an agent reads it, with and without GFC. Read it a few times, then edit it and read again.
On disk: const retries = 3. The model has seen nothing yet.
Without GFC
0 lines sentNothing read yet.
With GFC
0 lines sentNothing read yet.
Counts lines sent to the model, not tokens. A stub is one line here, though it costs about 70 tokens.
Measured, not vibes.
72-run A/B benchmark: 3 opencode free-tier models × 4 scenarios × 3 repetitions. Fresh sessions, identical prompts, GFC on versus parked. All attempts are counted, with no outlier removal. The harness ships in bench/.
- Context per turn, in tokens. Every bar uses one scale, so lengths compare across models too.
- Small files on a first read are unchanged, by design.
- The mechanism fired 9 of 9 times in every valid run. Comprehension after a stub: 100%. Zero re-fetch side effects.
- Free-tier prompt caching is nondeterministic, so benchmark with per-turn context totals, not raw input sums. Honesty notes are in the README.
Install in one command.
It finds OpenCode, Claude Code and Codex on your machine and wires each one. Your own settings and hooks are kept, and every changed file is backed up.
OpenCode, Claude Code, Codex
Automatic. A plugin for OpenCode’s read tool, hooks for shell reads in Claude Code and Codex.
curl -fsSL https://raw.githubusercontent.com/jjjebli/gfc/master/install.sh | bashRestart your agent. In Codex, type /hooks once and trust the GFC hooks. Re-run to update; --uninstall removes GFC and leaves your own hooks alone.
Any other MCP client
Advisory. Adds a gfc_read tool that your agent is instructed to prefer.
command: node
args: ["/Users/you/.gfc/mcp.mjs"]Works with Cursor, Gemini CLI, Windsurf and other MCP clients. Add a rule such as “prefer gfc_read over cat, head, sed, and tail” to your agent instructions.
Knobs.
Two environment variables, one reset, and a test suite that runs without an LLM or network access.
- GFC_HOME=/dir
- Relocates all state. Useful for isolating benchmarks or parallel installs.
- GFC_DEBUG=1
- Traces every hook decision to
~/.gfc/debug.log. - rm -rf ~/.gfc
- Full reset. Rebuilds itself on the next read and costs one full read per file. It’s a cache, so treat it like one.
- Tests
GFC_HOME=$(mktemp -d) node ~/.gfc/core.mjsandnode ~/.gfc/test.mjs. Deterministic, with no LLM and no network.
Known ceilings.
Stated up front, because a token-saving tool that oversells is a token-wasting tool. Open any of them for the details.
−Large rewrites get full content.
Diffs are multi-hunk (Myers), but past ~1000 changed lines, or when the diff would be over 80% of the file, the full content is sent instead. Diffs also apply only when the whole previous version was read.
−Files over 512 KB are never diffed.
They get a full re-read on change. Binary files are rejected outright by the MCP tool.
−The OpenCode hook depends on output mutation.
It relies on tool.execute.after output mutation, checked against the opencode 1.19.0 source. If the read format changes, verification fails closed: output passes through untouched. OpenCode’s unreleased 2.x plugin API will need a port.
−No savings without re-reads.
If your model reads a file once and never looks back, GFC does nothing. By design, it costs nothing too.