# How to Reduce opencode Token Usage

> opencode is BYO-key, so every wasted token is billed straight to you. Here's what actually drives the bill and which built-in controls are worth turning on.

Source: https://tokenade.net/en/articles/reduce-opencode-token-usage · Updated: 2026-10-15

Part of the [reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) pillar. Weighing it against another open agent? [opencode vs Kilo Code](https://tokenade.net/en/articles/opencode-vs-kilo-code). 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.

> Every wasted opencode token is billed to your key: Tokenade plugs into opencode and trims what it sends to the model.
>
> Install: `npm install -g @tokenade/cli && tokenade install` — or let your agent do it: https://tokenade.net/install.md

## 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 check opencode token usage?

Run `opencode stats` in your terminal. It is a documented OpenCode command that shows token usage and cost statistics for your OpenCode sessions. Add `--days 7` for the last week, `--models` for a per-model breakdown, `--tools` to see which tools pulled tokens in, and `--project ""` for the current project only.

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](https://github.com/anomalyco/opencode/issues/5374), "show tokens / second", open since December 2025 with 109 reactions. The pull request that implements it, [#12721](https://github.com/anomalyco/opencode/pull/12721), is also still open. Until one of them lands, the community plugin `@johannus22/opencode-tps-meter` puts a live rate in the TUI.

Worth being honest about what the number buys you. Tokens per second measures **throughput**, not spend: 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. The full picture — plugin status, how to measure a rate without a dependency, and why the input side is the one that bills — is in [opencode tokens per second](https://tokenade.net/en/articles/opencode-tokens-per-second).

## How do you reset an opencode limit?

You can't reset it by hand. OpenCode itself does not cap you: with your own key, the limit comes from your model provider and resets on that provider's schedule. On an OpenCode Go subscription, each model has a 5-hour, a weekly and a monthly allowance, and you wait for the window to roll over.

Per the [OpenCode Go docs](https://opencode.ai/docs/go/) (read 15 October 2026), the 5-hour limit is 20% of a model's monthly allowance and the weekly one 50%. If you have credits in your Console balance, the **Use balance** option makes Go fall back to pay-as-you-go instead of blocking requests.

Be wary of anything sold as an "opencode rate limit reset" download. No official tool does that, and the only thing that moves the limit is spending less of it per task.

## 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.**

1. **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.
2. **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.
3. **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.
4. **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.
5. **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

1. 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.
2. Switch exploratory work to the **`plan` agent** and keep `build` for when you know what you're changing.
3. Confirm **autocompact is on** (it is by default — just don't disable it and forget).
4. 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.
5. Then attack the reads. The tool-agnostic levers are in [how to reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage), and they apply unchanged here.

That last step is what [Tokenade](https://tokenade.net/en) 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](https://tokenade.net/en/stats/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](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) — the tool-agnostic pillar
- [How to reduce Claude Code token usage](https://tokenade.net/en/articles/reduce-claude-code-token-usage) — the same levers on Claude Code
- [Claude Code alternatives](https://tokenade.net/en/comparisons/alternatives/claude-code-alternatives) — where opencode fits among the options
- [Measure agent token usage](https://tokenade.net/en/articles/measure-agent-token-usage) — how to read the numbers you collect