{"slug": "opencode-token-usage-where-the-numbers-are-stored", "title": "OpenCode token usage: where the numbers are stored", "summary": "OpenCode stores per-message token counts — input, output, reasoning, cache read, cache write and a cost estimate — in a local SQLite database, usually opencode.db in the data directory, rather than keeping a single running session counter, so session totals must be computed by summing assistant-message records. The guide advises running `opencode debug paths db` to print the exact file path, since OPENCODE_DB and XDG_DATA_HOME can override it and some builds use a storage folder of JSON files instead. It warns that input already includes cached tokens and that reasoning is typically billed inside output, so adding those fields together double counts.", "body_md": "## Quick answer\n\nOpenCode stores token counts per assistant message in its local SQLite database, usually `opencode.db` inside the data directory. Each message keeps input, output, reasoning, and cache read and write counts plus a cost value. Run `opencode debug paths db` to print the exact file on your machine before you query it.\n\n## Tokens are attached to messages, not sessions\n\nOpenCode does not keep one running counter that says what a session cost. It writes a record for every assistant response, and the usage numbers travel inside that record. A session total is something you compute by adding those records together. That is why the same session can show one figure in the interface and a different figure in a spreadsheet.\n\n| Field | What it counts | Common mistake | \n|---|---|---|\n| input | Everything sent to the model, cached prefix included | Adding it to cache.read double counts | \n| output | Tokens generated, reasoning included on most providers | Adding reasoning again inflates the total | \n| reasoning | Thinking tokens, reported separately but billed as output | Summing it with output for a bill estimate | \n| cache.read | Input served from the provider's prompt cache | Treating it as free when it is billed at a lower rate | \n| cache.write | Tokens written into the cache for later turns | Ignoring it on providers that charge for writes | \n| cost | A per-message estimate from the provider or model rates | Assuming it matches your invoice exactly | \n\nRead the columns in the right order. `input` already includes the cached tokens the provider served, so fresh input is input minus cache read. If your provider bills cached input at a discount, keep the two apart rather than collapsing them into one number.\n\nReasoning is the second trap. Providers that bill internal thinking as output usually report it inside `output` and also expose it as `reasoning`. Adding both inflates the estimate. Check a single message against the provider's invoice before you trust any total built from these fields.\n\n## Find the file before you write a query\n\nGuessing the path wastes more time than the query. OpenCode ships a command that resolves the location for the current install after environment variables and the release channel are applied.\n\n```\nopencode debug paths db\nopencode debug paths data\nopencode debug paths\n```\n\n- Linux: `~/.local/share/opencode/opencode.db` , unless`XDG_DATA_HOME` is set\n- macOS: often `~/.local/share/opencode` , though some builds use`~/Library/Application Support/opencode`\n- Windows: `%APPDATA%\\opencode` , which expands to`C:\\Users\\<you>\\AppData\\Roaming\\opencode`\n- Any platform: `OPENCODE_DB` overrides the filename or path, so trust the printed result\n\nA path ending in `opencode.db` is a SQLite file. Older or differently configured builds may keep a `storage` folder of JSON files instead, with a similar message shape spread across many files. Your install may use one or the other, which is another reason to print the path first. The [database location guide](https://usageatlas.com/guides/opencode-database-location) covers both layouts in more detail.\n\n## Build a total you can trust\n\nA useful total answers a specific question. Daily spend, cost per model, and cost per session are three different queries, and mixing them produces a number nobody can act on.\n\n1. Filter to assistant messages, since user turns carry no usage.\n2. Sum each token column separately so you can recompute cost when rates change.\n3. Subtract cache read from input when you want fresh input, and label the column accordingly.\n4. Group by day, model, or session depending on the question you are answering.\n5. Store the raw counts in a CSV so a future price change does not rewrite history.\n\nDoing this by hand once is instructive. Doing it every week is not. [UsageAtlas](https://usageatlas.com/#download) reads the same database locally and totals tokens by session, model, and day across 7, 30, or 90 days, with alerts when a window runs low. It also keeps the per-message records available through the [cost field guide](https://usageatlas.com/guides/opencode-info-cost-field), so you can audit any total it shows.\n\n## Questions, answered\n\n### Does OpenCode show token usage in the terminal?\n\nSome builds surface context size or a per-message cost in the interface. The durable record is the message store. Run `opencode debug paths db` to find it, and check `opencode --help` for a stats command in your version.\n\n### Are OpenCode token counts the same as my provider bill?\n\nThey come from the usage the provider returns, but a bill can differ because of cached-token discounts, minimum charges, or rounding. Compare totals over the same date range rather than per request.\n\n### Why do extra small-model messages appear in my OpenCode usage?\n\nOpenCode uses a low-cost model to generate session titles, and those requests are recorded like any other. They are usually small but they are real usage, so filter by model before you blame a session.", "url": "https://wpnews.pro/news/opencode-token-usage-where-the-numbers-are-stored", "canonical_source": "https://usageatlas.com/guides/opencode-token-usage", "published_at": "2026-11-07 00:00:00+00:00", "updated_at": "2026-11-09 19:28:11.630934+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["OpenCode", "UsageAtlas", "SQLite"], "also_reported_by": [], "takeaway": "Sum OpenCode's per-message token columns separately and subtract cache.read from input for fresh input, since input already includes cached tokens and reasoning is usually billed inside output, so adding both inflates the total.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/opencode-token-usage-where-the-numbers-are-stored", "markdown": "https://wpnews.pro/news/opencode-token-usage-where-the-numbers-are-stored.md", "text": "https://wpnews.pro/news/opencode-token-usage-where-the-numbers-are-stored.txt", "jsonld": "https://wpnews.pro/news/opencode-token-usage-where-the-numbers-are-stored.jsonld"}}