Docs

Coding Agents

Costs and tokens

Costs and tokens: models, cache, monitoring 💰

Cost isn’t a surprise — it’s a lever 💰

Anyone who’s used a coding agent for a couple of weeks notices it immediately: the bill grows. That’s not a problem — it’s a signal.

An agent’s cost is not a footnote: it’s a strategic lever. The difference between efficient and wasteful usage lies in understanding tokens, cache, and model routing. Mastering these three factors means getting the same results at a fraction of the cost.

A wasted token isn’t just money — it’s latency, useless context, and a model reading things it doesn’t need.

Output costs more than input 💸

This is the first concept to internalize: every word the agent generates costs more than a word it reads. Not by a little — often 3-5x depending on the provider.

That means a vague prompt producing 2000 lines of useless output costs enormously more than a well-structured prompt producing 200. And the result? Often identical.

Some concrete strategies:

Short, direct prompts: cut preambles, superfluous context, unrequested examples
“Code only”: when code speaks for itself, ask for minimal output — no explanations, no redundant comments
Well-configured AGENTS.md: a clear context guide reduces the agent’s clarification questions, cutting output by ~20%
Structure your requests: a well-defined task prevents the agent from exploring useless paths

Golden rule: if you won’t read it, don’t ask the agent to generate it.

Model routing 80/15/5 🎯

Not all tasks require the same intelligence level. Using a frontier model to rename a variable is like driving a Ferrari to buy bread.

The practical rule that works: 80% lightweight models, 15% intermediate, 5% frontier.

Percentage	Type	Typical tasks
80%	Lightweight	Explanations, documentation, basic tests, mechanical refactors, renaming
15%	Intermediate	Multi-file features, medium logic, refactors with dependencies
5%	Frontier	High-risk architectural decisions, multi-step debugging, security reviews

This isn’t a hard constraint — it’s a default pattern. The key is developing the eye to know when a task needs a more powerful model and when it doesn’t.

The right model at the right time isn’t parsimony — it’s competence.

Cache rewards stability ⚡

Context caching is the hidden advantage of those who work well. If you switch models or tools mid-session, you invalidate the cache and costs start from zero.

Some best practices:

Don’t switch models mid-session: if you need to move from a lightweight task to a heavy one, consider opening a separate session rather than breaking context
Short, permanent instructions: put fundamental rules in AGENTS.md or equivalent — they load once and stay in cache
Stable context: avoid removing and re-adding files from context every turn
Compacted sessions: when the session grows too large, compress it rather than starting over

A well-constructed system prompt can reduce input consumption by 25-30% in long sessions, simply because the model doesn’t re-read the same instructions every turn.

Sub-agents vs infinite sessions 🤖

The classic temptation: keep a session open for hours, adding task after task. The result? Context growing exponentially, costs exploding, and a model losing track.

The alternative: delegate to sub-agents. Short tasks with scoped context reduce input consumption by up to 60% compared to the same work done in a continuous session.

How it works in practice:

The main task analyzes the problem and defines scope
Sub-agents receive only the context needed for their piece
Each sub-agent works in isolation, with minimal input
Results are assembled at the end

Complexity isn’t managed with more context — it’s managed with less context, but more strategically.

This pattern is particularly effective for broad refactoring, multiple tests, and migrations where each sub-task is independent.

Telemetry and budgets 📊

You can’t optimize what you don’t measure. But beware: telemetry without analysis is just numbers.

Practical strategies:

Usage dashboards: track tokens per session, per model, per task type — knowing how much you spend isn’t enough, you need to understand where you spend it
Thresholds with alerts: set alerts when consumption exceeds a threshold — better to stop and think than to proceed blindly
Periodic reviews: once a month, review usage patterns — you’ll always find tasks that could have used a lighter model or shorter session
Baseline comparison: measure average cost per task type and compare over time

The goal isn’t to minimize costs at all costs — it’s to maximize value per token spent.

When NOT to use the agent ⛔

Not every task needs an agent. Sometimes the wrong tool makes things worse:

Purely mechanical tasks with zero risk: renaming 50 variables is a find-and-replace, not a model task
Immediate visual debugging: if you see the bug looking at the code, fix it — no round-trip with the agent needed
Pure documentation research: if you know exactly where to look, go straight to the source
Repetitive tasks without variability: if you do it the same way every time, automate it with a script
When context is too large for the window: fragment first, delegate later — don’t force a model with too much data

The agent is an accelerator, not a replacement for thinking. Use it when it accelerates, not when it slows you down.

Final checklist ✅

Short, direct prompts — no preambles, no unrequested output
Conscious model routing — lightweight for 80%, intermediate for 15%, frontier for 5%
Cache preserved — same model, same tool, stable context within session
Sub-agents for independent tasks — scoped context, reduced input
Active telemetry — dashboards, thresholds, periodic reviews
Correct task matching — not everything needs an agent
Budget monitored — you know how much you spend and where
Compacted sessions — when it grows too large, compress