How to Reduce opencode Token Usage

Part of the reduce AI coding agent token usage pillar. This page is opencode-specific: the built-in controls, and what they do and don't cover.

How do you reduce opencode token usage?

Start by running opencode stats to see where the tokens actually went, use the plan agent for exploration instead of build, and leave automatic compaction on — then fix the biggest driver, which is almost always whole-file reads and unfiltered command output. opencode has a property that makes this both more urgent and easier than on subscription tools: it's bring-your-own-key. There's no plan absorbing your inefficiency and no wallet abstraction in the way. Every token you waste appears on your provider invoice at list price. That's uncomfortable, but it also means the feedback loop is honest — which is more than can be said for a tool that quietly meters you against an allowance. Quick note on identity, because most write-ups get it wrong: opencode is maintained by Anomaly (the team formerly known as SST), the repo is anomalyco/opencode, it's MIT-licensed and written in TypeScript. If you find a post describing it as "a Go project by SST", that's stale — and there's a separate, unrelated opencode-ai/opencode repo that isn't this.

Why does opencode burn tokens?

For the same structural reason every coding agent does: the model is stateless, so each turn resends the entire prior conversation plus everything the agent has read. Turn 20 carries turns 1 through 19, every file opened, every command output captured, every tool definition loaded. A "fix this failing test" prompt is forty tokens of your words and tens of thousands of tokens of context. The agent's cleverness doesn't change that arithmetic; the volume of what you feed it does. One opencode-specific detail is worth pulling out here, because it cuts the other way: it's LSP-enabled. A language server can answer "where is this symbol defined", "what are the references", "what's this type" without the agent opening and carrying whole files. That is exactly the substitution — structure instead of bodies — that this page keeps recommending, and it's already wired in. Whether the agent actually reaches for it rather than defaulting to a file read depends on how you've scoped the task, which is the part you control. What's specific to opencode is the surface area. It's model-agnostic across 75+ providers via the AI SDK, which is genuinely useful — but it also means your per-token rate is whatever you chose, and a careless model pick multiplies every inefficiency below. LSP integration and the built-in agents shape how much gets read in the first place.

How do you see opencode token usage in the first place?

opencode stats, and it takes four flags that turn a single number into a diagnosis. Run it bare and you get cumulative token usage and cost across your sessions. That's the headline, and on its own it tells you the size of the problem without telling you where it is. The flags are what make it useful:

--days N — restrict to the last N days. Defaults to all time, which blends your current habits with whatever you were doing three months ago.
--tools N — how many tools to list. This is the one that answers "what is actually eating my context", because tool calls are where the tokens enter.
--models N — model usage breakdown, hidden unless you ask. Pass a number for the top N. Being model-agnostic is opencode's advantage and this is the only way to check you're using it.
--project — filter by project. Pass an empty string for the current one.

Read the input/output split first. For nearly everyone input dominates output by roughly an order of magnitude, which decides where effort is worth spending: on what the agent reads, not on what it writes. If you want a ceiling on the write side anyway, OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX sets the maximum output tokens per LLM response. It's an experimental variable, so it may change or disappear, and it guards against one runaway generation rather than moving the monthly bill. Be clear about what stats cannot do: it is retrospective and aggregate. It will tell you that reads cost you 800k tokens last week. It will not tell you that 300k of those were the same four files re-read eleven times, which is the finding that actually changes your behaviour. For that you have to watch a live session, or put something between the agent and its tools.

Can opencode show tokens per second?

Not on its own. It is an open feature request, and a community plugin fills the gap today. The request is issue #5374, "show tokens / second", asking opencode to display current and average tokens/s so you can compare providers and models. It is still open, and so is the pull request attached to it, #12721, which adds tokens per second to the TUI response footer. If you are reading this and the footer already shows a rate, that PR landed after this page was written. Until then, opencode-tps-meter puts a live tokens-per-second meter with a visual bar into the opencode TUI. It is published on npm as @johannus22/opencode-tps-meter (0.1.2), and a separate fork at ChiR24/opencode-tps-meter targets both opencode generations as side-by-side binaries. Neither is an official plugin, so treat them the way you would any third-party TUI extension. Worth being honest about what the number buys you. Tokens per second measures throughput, not spend: it tells you which provider answers fastest, and it will not tell you which one costs least. A model at 120 tok/s that re-reads the same file four times is more expensive than one at 40 tok/s that reads it once. If the question behind "how fast is this going" is really "why is this costing so much", the input/output split from opencode stats above is the number to read instead.

Which built-in controls actually help?

Four of them, in rough order of impact.

opencode stats — shows token usage and cost statistics for your sessions, filterable by timeframe, tools, models and project. This is the one to run first. Every recommendation on this page is worth less than ten minutes with your own numbers, because the distribution of waste differs by codebase.
The plan agent — opencode ships two built-in agents: build has full access and is the default, plan is read-only. Exploration in plan avoids the write-path tool definitions and the edit-retry loops that inflate a session before you've decided what to change.
Automatic context compaction — on by default, and worth leaving on. You can disable it with OPENCODE_DISABLE_AUTOCOMPACT; the usual reason to do so is debugging a context problem, not saving money.
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX — caps maximum output tokens per response. Output is the expensive side per token, so this is a real guard against a runaway generation, though it's the smaller lever in practice because agent traffic is overwhelmingly inbound.

Also useful: opencode session list and session delete for pruning old sessions, and OPENCODE_DISABLE_PRUNE if you need to stop opencode discarding old data — note that's the knob that makes context bigger, so leave it alone unless you have a reason. I could not find documented prompt-caching controls in opencode's own docs. Caching behaviour will follow whatever your provider does by default, which for Anthropic means cache reads at 10% of input — significant enough that it's worth checking your provider's caching semantics rather than assuming.

What are the biggest levers for opencode specifically?

The ones that stop tokens entering the conversation, since compaction only helps after they're already in.

Read structure before bodies. An agent asking "where is the auth middleware defined" needs a symbol map, not four full files. Whole-file reads are the single largest line item in most sessions, and they're the easiest to over-supply because reading a file feels free.
Filter command output at the source. A failing test suite, a verbose build, a docker log — these arrive as thousands of tokens of which maybe twenty matter. They're then carried for the rest of the session.
Pick the model per task, not per session. Being model-agnostic is opencode's advantage; use it. Grunt work — reading and summarising, formatting, file listing — doesn't need your most expensive tier. On Claude, Haiku costs half of Sonnet 5 and a fifth of Opus.
Keep sessions short and scoped. Cost grows non-linearly with session depth because each turn re-sends everything prior. Two focused sessions cost less than one that wandered, even for the same work.
Audit tool definitions. Every tool available to the agent sits in context whether or not it's called.

What does an opencode session actually cost?

Enough that the model choice alone can swing the bill by 5×, and enough that re-reads dominate whatever you picked. Work it through with a session shape most people would recognise: fifty turns, ending with about a million input tokens carried across the conversation and forty thousand output tokens written. That's not an extreme case — it's a normal afternoon of multi-file work. On Claude Sonnet 5 at $2 per million input and $10 per million output, that's $2.00 of input and $0.40 of output: about $2.40, no caching. Move the same session to Opus 4.8 at $5/$25 and it's $5.00 plus $1.00 — $6.00. Drop the grunt-work portions to Haiku 4.5 at $1/$5 and the input side halves again. Same work, same agent, 5× spread, decided entirely by a config line. Two things fall out of that arithmetic. First, input is roughly 83% of the bill here, which is why "make the model write less" is the wrong instinct — output is priced 5× higher per token but arrives in far smaller volumes. Second, prompt caching matters more than model choice for repeated context: at 10% of input price on Anthropic, a stable prefix re-read across those fifty turns costs a tenth of what a fresh read does. So the order of operations is: cut what gets read, then let caching absorb what legitimately repeats, then pick the cheapest model that still does the job.

How to apply this today

Run opencode stats on the last week. Note the split between input and output — for most people input dominates by an order of magnitude, which tells you where to aim.
Switch exploratory work to the plan agent and keep build for when you know what you're changing.
Confirm autocompact is on (it is by default — just don't disable it and forget).
Set a model policy: cheap tier for grunt work, expensive tier for reasoning. With 75+ providers wired up, this costs you nothing but a config decision.
Then attack the reads. The tool-agnostic levers are in how to reduce AI coding agent token usage, and they apply unchanged here.

That last step is what Tokenade automates — it sits between the agent and its tools, retrieving instead of reading whole files, folding noisy command and MCP output at the boundary, without touching how you work. On the open token optimizer benchmark it cuts session cost by 39% on long sessions against running no tool at all.

What goes wrong (anti-patterns)

Treating compaction as the fix. Automatic compaction reduces what's carried forward; it doesn't stop a 3,000-token file from being read when twenty lines were needed. It's damage control, not prevention. Disabling autocompact to "keep more context". You'll pay for that context on every subsequent turn. If the agent is losing important detail, the answer is usually a tighter scope, not a bigger window. Choosing the most capable model for everything. BYO-key means this decision is fully yours and fully billed to you. It's the fastest way to multiply a token problem by five. Reading opencode stats once and never again. The distribution shifts as your codebase and habits change. It's a five-minute monthly check, not a one-off.

See also:

How to reduce AI coding agent token usage — the tool-agnostic pillar
How to reduce Claude Code token usage — the same levers on Claude Code
Claude Code alternatives — where opencode fits among the options
Measure agent token usage — how to read the numbers you collect