The Most Expensive File in Your Repo Isn't What You Think

The file you never optimized is the one bleeding your budget

CLAUDE.md, GEMINI.md, and AGENTS.md are instruction files that load into context on every single interaction with your AI coding agent. Every prompt you type, every tool call the agent makes, every file it reads: the instruction file rides along, consuming input tokens you pay for but never think about.

The thesis is simple: the teams burning through their token budgets fastest are the ones who never optimized these files. A bloated 800-line CLAUDE.md on a Pro plan at $20/month can eat 15-20% of your 5-hour rolling window before you type a single prompt. Caveman-compressing that file, and applying the same discipline to GEMINI.md and AGENTS.md, is the single highest-leverage optimization across all three major AI coding agents in May 2026.

The quick answer

What are these .md files?

CLAUDE.md (Claude Code), GEMINI.md (Antigravity/Gemini CLI), and AGENTS.md (OpenAI Codex) are project-level instruction files that tell the AI agent your coding conventions, architecture rules, and workflow preferences. They load into context on every interaction.

Why do they matter for cost?

Because they are constant "token tax." A 2,000-token instruction file costs you 2,000 input tokens on every single message, tool call, and agent loop iteration. Over a 50-interaction session, that is 100,000 tokens spent on instructions alone.

The non-obvious truth: Compressing these files with caveman-style prose, dropping articles, filler, and hedging while preserving all code blocks and technical terms, cuts input token cost by 40-60% per file. Combined with output compression, total session savings reach 20-40%.

How to set up each agent (and where the .md file lives)

All three agents follow the same pattern: install, authenticate, create the instruction file, start working. The setup takes under 10 minutes for each. The instruction file is where most teams stop optimizing.

Claude Code

Install on macOS or Linux with a single command:

curl -fsSL https://claude.ai/install.sh | bash

On Windows, use PowerShell:

irm https://claude.ai/install.ps1 | iex

Run claude in your terminal to authenticate via browser. You need a paid Anthropic plan: Pro ($20/month), Max 5x ($100/month), or Max 20x ($200/month). Alternatively, set ANTHROPIC_API_KEY for pay-per-token API access.

The instruction file is CLAUDE.md in your project root. Claude Code also reads ~/.claude/CLAUDE.md for global preferences. The hierarchy: global file loads first, project file layers on top, subdirectory files add specifics.

As of May 2026, Anthropic doubled the 5-hour rate limits for all plans and removed peak-hour throttling. The Pro plan budget sits at roughly 44,000 tokens per 5-hour rolling window, shared between Claude web and Claude Code. That budget evaporates fast when your CLAUDE.md alone consumes 2,000+ tokens per interaction. Antigravity vs Claude Code: Google IO Changed the Math breaks down the per-interaction economics in detail.

Antigravity CLI (formerly Gemini CLI)

Antigravity CLI is Google's Go-based terminal agent, the official successor to the Node-based Gemini CLI that sunsets for individual users on June 18, 2026. It shares the same agent harness as the Antigravity 2.0 desktop application.

Install via Google's developer portal for macOS, Linux, or Windows. Authenticate with your Google account or API key.

The instruction file is GEMINI.md (or .antigravity.md in newer setups). The hierarchy mirrors Claude Code: global at ~/.gemini/GEMINI.md, project root, then subdirectory overrides.

Pricing is per-token through the Gemini API. Gemini 3 Flash runs $0.50 per million input tokens and $3.00 per million output tokens. Gemini 2.5 Flash-Lite drops to $0.10/$0.40. Context caching cuts cached input costs by roughly 90%. There is a genuinely free tier with daily rate limits (1,500 requests per day on Flash-Lite), making Antigravity the only major coding agent where you can work without paying anything.

The 2-million-token context window on Gemini 3.1 Pro means you are less likely to hit hard context limits, but you still pay for every token that enters the window. A bloated GEMINI.md wastes money on Flash and wastes free-tier quota on Flash-Lite.

OpenAI Codex

Codex has evolved from a code completion model into a full agentic platform with a desktop app, CLI, and IDE extensions.

Install the CLI:

npm install -g @openai/codex

Access is included in ChatGPT Plus ($20/month), Pro, and Enterprise plans. API access uses standard OpenAI per-token pricing: $2.50-$5.00 per million input tokens for flagship models, $0.20-$0.75 for Nano/Mini.

The instruction file is AGENTS.md in your repo root. Like the others, it supports hierarchical placement: root for general rules, subdirectory files for service-specific guidance. How to Set Up Codex for Legacy Code Migrations covers the full setup including AGENTS.md structure for complex repos.

OpenAI recommends keeping AGENTS.md under 150 instructions. Past that threshold, model adherence drops and reasoning token consumption rises. Codex vs Claude Code vs Gemini CLI: May 2026 Verdict benchmarks the three agents head-to-head on real tasks.

Why is the .md file your most expensive file?

The instruction file is the only file in your repo that loads into context on every single interaction. Your source code loads selectively, when the agent reads or edits specific files. Your dependencies never load. But CLAUDE.md, GEMINI.md, and AGENTS.md ride along on every prompt, every tool invocation, every reasoning loop.

The math is straightforward. A typical agentic coding session involves 30-80 interactions (prompts, tool calls, file reads, edits). If your instruction file is 2,000 tokens, that is 60,000 to 160,000 input tokens consumed by instructions alone. On Claude Code Pro at roughly 44,000 tokens per 5-hour window, the instruction file can consume more than the entire session budget if the session runs long.

On Antigravity with Gemini 3 Flash at $0.50 per million input tokens, a 2,000-token instruction file over 80 interactions costs $0.08 per session. Small, until you run 10 sessions a day: $0.80/day, $24/month, just on the instruction file. On flagship models at $2-4 per million tokens, that scales to $96/month.

On Codex with GPT-5 flagship at $5.00 per million input tokens, the same pattern costs $0.80 per session, $8/day at 10 sessions.

The instruction file is a multiplier. Every token you add to it gets multiplied by every interaction in every session for the rest of the project's life. No other file in your repo has that cost structure.

What is caveman compression and why does it work?

Caveman is a plugin (by Julius Brussee, GitHub) that forces AI agents to communicate in compressed, telegraphic prose. The tagline: "why use many token when few do trick."

The technique has two halves:

1. Output compression makes the agent's responses shorter by dropping articles, filler words, pleasantries, and hedging. Code blocks, URLs, file paths, and technical terms are preserved exactly. Average output token savings across real tasks: 65%, with a range of 22-87% depending on the task.
2. Input compression (caveman-compress) rewrites your instruction files into the same telegraphic style. A typical CLAUDE.md compressed with caveman-compress shrinks by 46% in token count. Preferences files shrink by 59.6%, project documentation by 43.3%.

The key insight: a March 2026 paper found that constraining large models to brief responses actually improved accuracy by 26 percentage points on certain benchmarks. Verbose output is not more accurate output. The model's internal reasoning (thinking tokens) stays the same; only the "mouth" gets smaller.

Here is what caveman compression looks like in practice:

Before (standard CLAUDE.md, 47 tokens):

When working with this project, please always use TypeScript 
for all new files. We prefer functional components with React 
hooks rather than class components. Please make sure to run 
the linter before committing any changes.

After (caveman-compressed, 19 tokens):

TS all new files. Functional components + hooks, no classes. 
Run linter pre-commit.

Same information. 60% fewer tokens. Multiply by every interaction in every session.

Intensity levels

Caveman offers four intensity levels. Pick one and stick with it:

For instruction files, Full is the sweet spot: maximum compression with zero ambiguity.

How to optimize each .md file (step by step)

CLAUDE.md optimization

How to Set Up Claude Code for Real SEO Work covers the full CLAUDE.md setup. Here is how to cut its token cost:

1. Target under 500 tokens. If your CLAUDE.md is over 500 tokens, it is too long. Audit every line: does the agent need this on every single interaction, or only sometimes?
2. Use pointers, not content. Instead of pasting your style guide into CLAUDE.md, write: Style guide: see docs/STYLE.md. Claude reads referenced files only when relevant, not on every interaction.
3. Run caveman-compress:

claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

Then: /caveman:compress CLAUDE.md. The original is backed up as CLAUDE.original.md.

1. Use .claudeignore to prevent indexing irrelevant files (node_modules, build artifacts, lock files). Less indexing = fewer tokens spent on context.
2. Do not change CLAUDE.md mid-session. Modifications reset prompt caching, forcing full-price reprocessing of the entire conversation history.
3. Session hygiene: Run /compact after each major phase to compress conversation history. Run /clear when switching tasks entirely. Use /cost to track consumption.

GEMINI.md optimization

The same principles apply, with Antigravity-specific tactics:

1. Keep under 2,000 tokens (Antigravity's instruction files can be longer because context caching is more aggressive, but shorter is still cheaper).
2. Structure with protocols. Organize instructions into gated blocks (<PROTOCOL:EXPLAIN>, <PROTOCOL:IMPLEMENT>) so the agent only processes relevant instructions for the current task mode.
3. Use .antigravityignore (or .geminiignore) to exclude node_modules, build outputs, and lock files from indexing.
4. Apply caveman compression:

gemini extensions install https://github.com/JuliusBrussee/caveman

Then run the compress command on your GEMINI.md.

1. Use custom slash commands (.antigravity/commands/*.toml) for repetitive tasks instead of writing instructions into GEMINI.md.
2. Exploit context caching. Gemini's cached input tokens cost roughly 90% less. Keep stable instructions at the top of GEMINI.md so they cache reliably.

AGENTS.md optimization

1. Under 150 instructions. OpenAI's own guidance: exceeding 150-200 instructions decreases model adherence and increases reasoning tokens.
2. Use progressive disclosure. Concise main AGENTS.md pointing to task-specific docs. Subdirectory AGENTS.md files for service-specific rules.
3. Remove discoverable information. Do not duplicate what is already in your README, package.json, or code comments. The agent reads those files directly.
4. Place static instructions first in the file for caching benefits. OpenAI optimizes for exact prefix matches.
5. Install caveman for Codex: Clone the repo into your plugins directory, or use npx skills add JuliusBrussee/caveman.
6. Right-size models. Nano for simple edits, Mini for standard work, flagship for complex architecture. Model routing is the single biggest cost lever on Codex.

The compounding math most teams miss

Caveman compression works on both sides: input (compressed instruction files) and output (compressed agent responses). The savings compound.

A typical unoptimized session on Claude Code Pro:

• Instruction file: 2,000 tokens x 50 interactions = 100,000 input tokens
• Agent responses: 800 tokens average x 50 = 40,000 output tokens
• Total: 140,000 tokens

The same session with caveman on both sides:

• Compressed instruction file: 1,000 tokens x 50 = 50,000 input tokens (50% saved)
• Compressed responses: 280 tokens average x 50 = 14,000 output tokens (65% saved)
• Total: 64,000 tokens

That is a 54% reduction. On a Pro plan with 44,000 tokens per 5-hour window, that is the difference between hitting the limit every 2 hours and lasting the full 5-hour window.

On Antigravity with Gemini 3 Flash, the dollar impact at 10 sessions/day:

• Before: $0.08/session x 10 = $0.80/day = $24/month
• After: $0.037/session x 10 = $0.37/day = $11/month

On Codex with GPT-5 flagship at 10 sessions/day:

• Before: $0.80/session x 10 = $8/day = $240/month
• After: $0.37/session x 10 = $3.70/day = $111/month

The percentage savings are roughly the same across all three platforms because caveman targets a universal inefficiency: natural language is not optimized for token density.

The honest take

Caveman is not free. Compressed output is harder to read. If you are learning a new codebase and need the agent to explain concepts in full prose, caveman at Ultra intensity will make you slower, not faster. Lite or Full intensity is the right default; save Ultra for production workflows where you already understand the code.

The 65% output savings figure comes from the caveman plugin's own benchmarks. Real-world session savings are typically 4-10% when you account for input tokens from code files, conversation history, and tool outputs that caveman does not compress. The instruction file optimization is where the reliable, repeatable savings live.

The token budgets published here, especially Claude Code's 44,000 tokens per 5-hour window, are estimates. Anthropic does not publish fixed numbers; limits fluctuate with system load, model choice, and conversation complexity. Plan conservatively.

Claude Agent SDK for Customer Support Triage demonstrates how the same token discipline applies when building production agents, not just coding with them.

The bottom line

Your .md instruction file is a multiplier: every token in it gets charged on every interaction for the life of the project. Optimize it first, optimize it once, and the savings compound across every session you run.

Three moves, in order of impact:

1. Compress your instruction file with caveman (40-60% input token savings on that file).
2. Enable caveman output mode to cut response verbosity by 65% on average.
3. Practice session hygiene: /compact between phases, /clear between tasks, right-size your model.

The agents are expensive because natural language is expensive. Make it cheaper.

FAQ

Does caveman compression change the agent's reasoning quality?

No. The agent's internal reasoning (thinking/chain-of-thought tokens) is unaffected by caveman. Only the output format changes. A March 2026 study found that constraining output brevity actually improved accuracy by 26 percentage points on some benchmarks.

Can I use caveman across all three agents simultaneously?

Yes. Caveman installs as a plugin on Claude Code, an extension on Antigravity/Gemini CLI, and via the skills system on Codex. The core technique (telegraphic prose, preserved code blocks) works identically on all three.

What if my team finds compressed instruction files hard to read?

Keep the original as a reference (CLAUDE.original.md). The compressed version is for the agent; humans read the original. The caveman-compress tool backs up the original automatically.

How small should my instruction file actually be?

For CLAUDE.md: under 500 tokens. For GEMINI.md: under 2,000 tokens (Gemini's aggressive context caching makes larger files less costly). For AGENTS.md: under 150 instructions (roughly 800-1,000 tokens). Smaller is always cheaper.

Does this work with API-based usage or only subscription plans?

Both. On subscription plans (Claude Pro, ChatGPT Plus), caveman helps you stay within your rolling window budget. On API plans, it directly reduces your per-token bill. The percentage savings are the same either way.

Is there a risk of the agent misunderstanding compressed instructions?

At Lite and Full intensity, no. The compression preserves all technical terms, code blocks, file paths, and commands exactly. Only filler and natural language scaffolding is removed. At Ultra intensity, heavy abbreviation (DB for database, fn for function) can introduce ambiguity in edge cases.

Should I compress my README too?

No. README.md is read by humans, not loaded into every agent interaction. Only compress files that the agent loads on every interaction: CLAUDE.md, GEMINI.md, AGENTS.md, and any always-loaded skill files.

Which agent gives the best free tier for someone just starting?

Antigravity/Gemini CLI with Flash-Lite. It is the only major coding agent with a genuinely free tier (1,500 requests/day). Claude Code and Codex both require paid plans