A context budget for coding agents means measuring what the agent loads before it starts work. The visible prompt is only one part. Instructions, tools, MCP, history, memory and subagents also enter the cost and can change the outcome.
In July 2026, Systima published a traffic measurement between coding-agent harnesses. In that test, Claude Code sent about 33k tokens before reading the prompt, while OpenCode sent about 7k (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). That number does not prove one tool is better. It proves context needs a budget.
Practical summary
- Measure the baseline before blaming the model.
- Cut always-loaded instruction, not useful knowledge.
- MCP and subagents count in the task budget.
- CI should record context, tools and exceptions.
Why does the cost appear before the prompt?
In 2026, Systima measured about 33k tokens sent by Claude Code before the prompt, compared with about 7k in OpenCode (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). That cost comes from the harness: system text, tools, schemas, memories, instructions and reminders that arrive before the task.
The agent does not start empty. It loads tool contracts, execution policy, persistent instructions, conversation state and repository cues. In a short loop, that cost may feel acceptable. In a long loop, it becomes a recurring tax on each attempt, test, fix and review.
That is what many teams miss when optimizing prompts. The prompt can be lean while the agent still carries a large package of automatic context. The right work starts with a simple question: what entered the model before the user request?
Citable capsule: A context budget for coding agents starts before the visible prompt. Systima's 2026 measurement found about 33k initial tokens in Claude Code and about 7k in OpenCode, showing that harness and configuration define the operational floor.
What should you measure before cutting context?
In 2026, Systima reported that a 72 KB instruction file added just over 20k tokens per request in both tested harnesses (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Before cutting content, separate baseline, instructions, tools and history into auditable categories.
I start with five measurements. Baseline is the payload without a real task. The instruction layer covers AGENTS.md, CLAUDE.md and path rules. The tool layer covers MCP schemas and internal tools. The history layer covers chat, shell outputs and diffs. The fan-out layer covers subagents.
This separation prevents bad cuts. Removing test commands from the instruction file may save context, but it can weaken verification. Removing duplicated architecture that the agent can discover with rg is usually safer. For the foundation, see context engineering for coding agents.
Practical note: when a session gets expensive, I save the loaded instruction files, available tools and subagents called. Without that inventory, the discussion becomes an opinion about the model, not system engineering.
How do you shrink AGENTS.md and CLAUDE.md without breaking the agent?
In 2026, "Evaluating AGENTS.md" concluded that context files increased average inference cost by more than 20% and did not generally improve task success in the evaluated settings (arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", 2026). Persistent instruction therefore has to prove value.
AGENTS.md and CLAUDE.md should not be duplicated READMEs. They should contain what the agent needs in every task: test commands, security limits, unusual conventions, done criteria and real repository traps. Everything else can live in searchable documentation.
Claude Code documentation says CLAUDE.md is loaded into the session context and recommends targeting under 200 lines per file (Claude Code Docs, "How Claude remembers your project", 2026). Codex documentation says AGENTS.md is read before work begins and that the default combined project-instruction limit is 32 KiB (OpenAI, "Custom instructions with AGENTS.md", 2026).
Good cuts are surgical. Replace directory trees with search patterns. Replace long policy prose with verifiable rules. Replace rare procedures with on-demand skills. If the post on lean AGENTS.md for agents is the editorial layer, this article is the measurement layer.
Citable capsule: A good instruction file reduces ambiguity without loading the whole documentation set. arXiv measured average cost above 20% with AGENTS.md, while Claude Code recommends under 200 lines and Codex sets 32 KiB as the default combined limit.
When do MCP and subagents enter the budget?
In 2026, Systima measured small MCP servers adding about 1k to 1.4k tokens per server per request, while a modest subagent fan-out multiplied the measured total by 4.2x (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Tools and delegation need explicit limits.
MCP is worth it when it prevents pasting live context into the prompt. It is not worth it when every server stays enabled by default. Codex best practices recommend adding tools only when they unlock a real workflow, starting with one or two clear integrations (OpenAI, "Best practices", 2026).
Subagents follow the same logic. They work well for parallel research, domain migrations and independent review. But each subagent may load its own bootstrap, tools and history. When the job is small, calling a subagent can cost more than solving it directly.
For long Claude Code or Codex loops, I use RemoteCode as a layer that helps agents go further with less wasted context. It is my own tool, so this is an editorial recommendation: it helps with context and coordination bottlenecks, not with budgeting, sandboxing or review by itself.
Citable capsule: MCP and subagents are context multipliers. Systima measured about 1k to 1.4k tokens per small MCP server and a 4.2x token increase in a modest fan-out; use these layers when they remove real work.
How do you turn a context budget into a CI gate?
In 2026, Systima measured a real configuration with roughly 75k tokens in Claude Code and 90,817 tokens in OpenCode before useful work, combining MCP, plugins and a large instruction file (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). CI should make that cost visible.
A simple gate does not need to know price. It needs to record change. Capture which instruction files loaded, how many tools were available, which MCP servers entered, which subagents ran and what the payload looked like before the first code action.
The gate should fail when configuration changes without review. A new MCP server, a large import in CLAUDE.md, a skill that injects a long checklist or a subagent created for a small task should appear in the PR. This pairs with PR evals for agents in CI and self-correcting loops in CI.
Citable capsule: A context-budget gate does not need to calculate token price. It needs to detect drift: larger instructions, new MCP, more tools, extra subagents and a larger initial payload. Systima's measured configuration shows the real cost comes from the whole stack.
A simple harness for auditing tokens per task
In 2026, "Configuration Smells in AGENTS.md Files" analyzed 100 popular repositories and found Lint Leakage in 62% of files, Context Bloat in 42% and Skill Leakage in 35% (arXiv, "Configuration Smells in AGENTS.md Files", 2026). Those smells become useful criteria for an audit harness.
The harness should run before the main agent. It lists instructions, detects duplication, measures size, records tools and requires a reason for fan-out. Then it stores the summary as a CI artifact. It does not need to expose secrets or capture sensitive content; the goal is to track structure, not leak prompts.
An operating contract can look like this:
context:
measure_baseline: true
record_instruction_files: true
record_tools: true
record_mcp: true
record_subagents: true
policy:
block_unreviewed_instruction: true
block_unreviewed_mcp: true
require_reason_for_fan_out: true
output:
ci_artifact: ".ci/context-budget/report.json"
pr_summary: ".ci/context-budget/summary.md"The next step is to connect this harness to review. If a PR changes AGENTS.md, CLAUDE.md, .claude/rules, .mcp.json or agent skills, the budget should appear as evidence. Otherwise, the team discovers the cost only after the session is already slow, expensive or unstable.
Citable capsule: A context harness for agents measures structure before price. Since a 2026 study found Context Bloat in 42% of analyzed AGENTS.md or CLAUDE.md files, CI should treat persistent instruction as a performance and review surface.
Safe-cut checklist
In 2026, "Probe-and-Refine Tuning of Repository Guidance" reached a 33.0% mean resolve rate on SWE-bench Verified, compared with 28.3% from the initial static base and 25.5% without guidance (arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", 2026). The message is balanced: bad context hurts, but refined guidance helps.
Use this checklist when the agent is costly, slow or unfocused:
- Remove overview material the agent can discover through search.
- Keep build, test and lint commands that are actually used.
- Move rare procedures into skills or on-demand runbooks.
- Prefer path rules for specialized areas.
- Review imports in
CLAUDE.md; they expand context. - Enable MCP only when the task needs live external data.
- Require a reason before subagent fan-out.
- Record context drift in the PR.
The goal is not to blind the agent. It is to give enough context for it to find the right file, run the right proof and stop carrying irrelevant material. In coding agents, token economy is also reliability engineering.
Frequently asked questions about context budgets
Is a context budget just about cutting tokens?
No. In 2026, Anthropic described context engineering as curating the smallest set of high-signal tokens that maximizes the desired outcome (Anthropic, "Effective context engineering for AI agents", 2026). The budget measures cost, but the decision is about relevance, verifiability and control.
Does AGENTS.md always make the agent worse?
No. In 2026, "Probe-and-Refine" showed a 33.0% mean resolve rate against 25.5% without guidance in its experiment (arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", 2026). The problem is generic, bloated or untested context, not the existence of the file.
Should MCP stay off by default?
For most repositories, yes. In 2026, Systima measured about 1k to 1.4k tokens per small MCP server per request (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Enable MCP when it replaces real manual work, not as decoration.
Are subagents a waste of context?
Not necessarily. In 2026, Anthropic described subagents as a way to isolate extensive searches and return smaller summaries to the lead agent (Anthropic, "Effective context engineering for AI agents", 2026). Use fan-out when parallelism reduces risk or time, and record the cost in the harness.
Sources
- Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", retrieved 2026-07-14, https://systima.ai/blog/claude-code-vs-opencode-token-overhead
- Claude Code Docs, "How Claude remembers your project", retrieved 2026-07-14, https://code.claude.com/docs/en/memory
- Anthropic, "Effective context engineering for AI agents", retrieved 2026-07-14, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- OpenAI, "Custom instructions with AGENTS.md", retrieved 2026-07-14, https://developers.openai.com/codex/guides/agents-md
- OpenAI, "Best practices", retrieved 2026-07-14, https://developers.openai.com/codex/learn/best-practices
- arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", retrieved 2026-07-14, https://arxiv.org/abs/2602.11988
- arXiv, "Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents", retrieved 2026-07-14, https://arxiv.org/abs/2606.15828
- arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", retrieved 2026-07-14, https://arxiv.org/abs/2606.20512
