{"_id":"@aeondave/opencode-tokenomics","name":"@aeondave/opencode-tokenomics","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aeondave/opencode-tokenomics","version":"0.1.0","description":"Real-time token usage & cost dashboard for OpenCode, split by project. Boots a local web server on startup and opens it in the browser.","keywords":["opencode","opencode-plugin","tokens","cost","usage","dashboard","observability"],"homepage":"https://github.com/AeonDave/opencode-tokenomics#readme","bugs":{"url":"https://github.com/AeonDave/opencode-tokenomics/issues"},"repository":{"type":"git","url":"git+https://github.com/AeonDave/opencode-tokenomics.git"},"license":"MIT","type":"module","main":"src/plugin/index.ts","exports":{".":"./src/plugin/index.ts"},"scripts":{"typecheck":"tsc --noEmit","test":"bun test","dashboard:dev":"npm --prefix dashboard run dev","dashboard:build":"npm --prefix dashboard run build"},"peerDependencies":{"@opencode-ai/plugin":"*","@opencode-ai/sdk":"*"},"peerDependenciesMeta":{"@opencode-ai/plugin":{"optional":true},"@opencode-ai/sdk":{"optional":true}},"devDependencies":{"@opencode-ai/plugin":"^1.17.4","@opencode-ai/sdk":"^1.17.4","@types/bun":"latest","fast-check":"^4.8.0","typescript":"latest"},"gitHead":"169d8b8df45e1f18e6b8c06108ccc4092e2d6e09","_id":"@aeondave/opencode-tokenomics@0.1.0","_nodeVersion":"26.3.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-ZOkkL4unFStVs9BhHfKRQccWdjxDVPtmyR3uGt7XPdAHkeGwJlbTPY4oXMUwuowNd+DSC7VMlucvKiow5cKfsA==","shasum":"135852d7d2c119263c537a731c9dc626ce4068aa","tarball":"https://registry.npmjs.org/@aeondave/opencode-tokenomics/-/opencode-tokenomics-0.1.0.tgz","fileCount":24,"unpackedSize":949683,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCRmNnhKSG6Cl0ZpkGh7mjUUS6iMaqcFtlDs4mcdnDhDAIgQ07qBCnk32fd1q8Zc8HwCCEwGX/8BhkkhDpLVNloJTU="}]},"_npmUser":{"name":"aeondave","email":"nova.davide@gmail.com"},"directories":{},"maintainers":[{"name":"aeondave","email":"nova.davide@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-tokenomics_0.1.0_1781704630808_0.767488269650237"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T13:57:10.626Z","0.1.0":"2026-06-17T13:57:11.017Z","modified":"2026-06-17T13:57:11.250Z"},"maintainers":[{"name":"aeondave","email":"nova.davide@gmail.com"}],"description":"Real-time token usage & cost dashboard for OpenCode, split by project. Boots a local web server on startup and opens it in the browser.","homepage":"https://github.com/AeonDave/opencode-tokenomics#readme","keywords":["opencode","opencode-plugin","tokens","cost","usage","dashboard","observability"],"repository":{"type":"git","url":"git+https://github.com/AeonDave/opencode-tokenomics.git"},"bugs":{"url":"https://github.com/AeonDave/opencode-tokenomics/issues"},"license":"MIT","readme":"# opencode-tokenomics\n\nReal-time **token usage & cost** for [OpenCode](https://opencode.ai), split by project, in a live web dashboard.\n\nWhen opencode starts, this plugin boots a small local web server and opens a dashboard in your\nbrowser. It listens to opencode's event stream and shows — live, as you work — how much each\n**project**, **model**, and **subagent** is spending, with cache-efficiency and savings analysis.\nIt's **always-on, real-time, per-project, and in a real UI with charts** rather than a one-shot\ntext report.\n\n![Dashboard overview](assets/dash1.png)\n\n![Dashboard charts & breakdowns](assets/dash2.png)\n\n---\n\n## What you get\n\n- **Live spend** — total USD cost, tokens, and API calls, updating in real time over SSE.\n- **Per-project split** — usage is keyed by project root, so every repo you touch is tracked\n  separately, navigable from a searchable, sortable sidebar that scales to hundreds of projects.\n- **Agents & subagents** — child sessions shown as a tree with *who* (agent), *what* (title/model),\n  *how much* (cost/tokens/calls) and *how long* (wall-clock duration) for each.\n- **Agent × model** — cross-breakdown of which agent spent how much on which `provider/model`.\n- **By model** — cost and tokens per `provider/model`.\n- **Cache efficiency** — cache hit rate, and the **real** money caching saved (counted only where\n  opencode actually billed a per-token cost, so free/self-hosted usage never shows phantom savings).\n- **Token distribution** — fresh input / cache read / output / cache write channels.\n- **Context breakdown** — estimated split of input tokens across system prompt, tool definitions,\n  environment, project tree and custom instructions.\n- **Tool usage** — per tool: call count, **failed calls**, estimated output tokens, schema size, complexity, total time.\n- **Skills loaded** — which skills were loaded (via the `skill` tool), how many times, and the tokens of skill content pulled into context.\n- **Reliability** — errored assistant messages and provider retries, rolled up per model, per session and overall.\n- **Charts** — cumulative spend, **spend over time stacked by model**, **tokens by day** (by channel),\n  **activity by hour of day**, and **cost efficiency ($/M tokens) per model**.\n- **Configurable cards** — a settings panel (gear, top-right) toggles every card on/off and saves to\n  `~/.config/opencode/tokenomics.json`. Hidden cards are also **skipped in computation**, so heavy\n  views don't tax low-resource machines. Everything starts on.\n- **Real vs estimated cost** — \"Spend\" is always what opencode actually bills (so a **free** model\n  reads `$0`/`free`, never phantom spend). On subscription/zen plans that report `cost: 0`, a clearly\n  labeled `~$x` / \"≈ at API rates\" estimate is shown alongside so you still gauge API-equivalent value.\n\n## How it works\n\n```\nopencode (Bun)                          your browser\n┌───────────────────────────┐          ┌─────────────────────────────┐\n│ plugin (src/plugin)       │   SSE    │ dashboard (Vite+React+      │\n│  events → aggregator      │ ───────► │  shadcn/ui + recharts)      │\n│  per-project snapshots    │  /api/   │  KPIs · charts · tree       │\n│  Bun.serve on :5757 ──────┼──────────┤  served from dashboard/dist │\n└──────────┬────────────────┘          └─────────────────────────────┘\n           │ persists snapshots to ~/.local/share/opencode/tokenomics\n           ▼\n   projects/<key>.json   ← also read/merged across opencode windows\n```\n\n- The plugin translates `message.updated` (assistant billing), `session.created/updated`\n  (subagent tree), and tool/agent message parts into per-project `UsageRecord`s.\n- The first opencode instance to grab the port runs the web server; other instances (other\n  projects/windows) act as writers, and their data reaches the dashboard through the shared\n  data directory — so the dashboard shows **all** your projects at once.\n- Costs come straight from opencode when available; otherwise they're estimated from\n  `pricing.ts` (override in `~/.local/share/opencode/tokenomics/pricing.json`).\n\n## Installation\n\n### From npm\n\nAdd the package to the plugin array in your OpenCode config at `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"plugin\": [\"@aeondave/opencode-tokenomics@latest\"]\n}\n```\n\nOpenCode installs the plugin and its dependencies automatically on the next start. To pin a\nversion, replace `@latest` with a specific version (e.g. `@0.1.0`). The published package ships\nthe built dashboard, so nothing else is needed — restart OpenCode and it opens the dashboard.\n\n### From source (git clone)\n\nRun from a local checkout — useful before publishing or while hacking on the plugin.\n\nClone the repository and install dependencies (plugin + dashboard), then build the dashboard once\n(the plugin serves the built assets from `dashboard/dist`):\n\n```bash\ngit clone https://github.com/AeonDave/opencode-tokenomics.git\ncd opencode-tokenomics\nbun install\nnpm --prefix dashboard install\nnpm run dashboard:build      # outputs dashboard/dist\n```\n\nCreate a shim file in your global plugin directory that re-exports the checkout's entry point. The\ndirectory is `plugin` (singular):\n\n- Path: `~/.config/opencode/plugin/tokenomics.ts`\n- Content — a single line pointing at the absolute path of the cloned entry point:\n\n```ts\nexport { default } from \"/absolute/path/to/opencode-tokenomics/src/plugin/index.ts\"\n```\n\nOn Windows, use forward slashes and include the drive letter:\n\n```ts\nexport { default } from \"C:/opencode-tokenomics/src/plugin/index.ts\"\n```\n\nRestart OpenCode. On startup it prints `[tokenomics] live dashboard → http://localhost:5757` and\nopens it. The plugin loads from your working tree, so edits to `src/` take effect on the next\nrestart. Delete the shim file to uninstall. Until you build the dashboard, a built-in live page is\nserved instead (same data, fewer charts).\n\nUse one method at a time. If you add the npm entry, remove the local shim (and vice versa) to avoid\nloading the plugin twice.\n\n## Dashboard development\n\n```bash\nnpm --prefix dashboard run dev   # Vite dev server on :5173, proxies /api → :5757\n```\n\nRun opencode (so the plugin server is up on :5757), then open the Vite dev URL for hot reload.\n\n## Configuration (environment variables)\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `OPENCODE_TOKENOMICS_PORT` | `5757` | Preferred web server port (auto-scans upward if busy) |\n| `OPENCODE_TOKENOMICS_DIR`  | `~/.local/share/opencode/tokenomics` | Data directory |\n| `OPENCODE_TOKENOMICS_OPEN` | (on) | Set to `0` to not auto-open the browser |\n\nThe port is a *preferred* starting point: if it's taken by another server (e.g. another plugin),\ntokenomics scans upward to the next free port and opens the browser there. A second opencode window\ndetects the running tokenomics server and shares it (one dashboard, all projects) instead of\nstarting a duplicate.\n\n`pricing.json` in the data dir overrides per-model rates (USD per 1M tokens):\n\n```json\n{ \"anthropic/claude-opus-4-8\": { \"input\": 5, \"output\": 25, \"cacheRead\": 0.5, \"cacheWrite\": 6.25 } }\n```\n\nSet every rate to `0` to treat a model as free — handy for **self-hosted / custom providers** whose\nid doesn't contain `free` (e.g. a local vLLM model), so they don't show an API-rate estimate.\n\n## API\n\n- `GET /api/health` → `{ ok: true, service: \"opencode-tokenomics\" }`\n- `GET /api/stats` → merged `GlobalSnapshot` (all projects)\n- `GET /api/stream` → `text/event-stream`, pushes the `GlobalSnapshot` on every change\n- `GET /api/config` → `{ cards: { <id>: boolean } }` (which cards are enabled)\n- `PUT /api/config` → body `{ cards }` — persists the card selection to `~/.config/opencode/tokenomics.json`\n- `DELETE /api/projects/:key` · `DELETE /api/projects` → delete one project's stored data, or all\n\n## Notes & limitations\n\n- Per-token cost is taken from opencode when present; the price table is a fallback/estimate.\n- Genuinely free models (id contains a `free` token, e.g. `deepseek-v4-flash-free`, `…:free`) are\n  treated as `$0` with no estimate — their tokens are still tracked, only the dollar figure is zero.\n- The cache-savings figure counts only records opencode actually billed (real cost > 0): it's the\n  difference between paying full input price and the cache-discounted price at table rates. Free,\n  self-hosted and subscription ($0) usage contributes no savings — caching saves no *real* money there.\n- The native input/output/cache/reasoning token channels are **exact** (straight from opencode).\n  The context breakdown, per-tool output/schema sizes and tool complexity are **estimates** from a\n  lightweight, dependency-free tokenizer (`~chars/4` blended with word count) applied to the system\n  prompt and tool schemas — good for proportions, not billing.\n\nMIT\n","readmeFilename":"README.md","_rev":"1-07a72e4a5896b998faa6f3cf2ff55ae0"}