opencode-tokscale 0.0.1-rc.0

package/README.md

@@ -0,0 +1,116 @@
+# opencode-tokscale
+
+A [opencode](https://opencode.ai) TUI sidebar plugin for [tokscale](https://github.com/junhoyeo/tokscale). Shows token usage and costs for today, this week, and this month.
+
+```
+Tokscale
+Today        1.2M    $3.45
+This Week    5.6M   $12.34
+This Month  12.3M   $45.67
+```
+
+## Install
+
+### Prerequisites
+
+[tokscale](https://github.com/junhoyeo/tokscale) must be installed:
+
+```bash
+npm i -g @tokscale/cli
+```
+
+If tokscale isn't found, the plugin shows an install prompt instead of stats.
+
+### Setup
+
+One config file. Restart. Done.
+
+**`~/.config/opencode/tui.json`**
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [["opencode-tokscale", { "enabled": true }]]
+}
+```
+
+opencode resolves the npm package on startup automatically.
+
+### Options
+
+```json
+{
+  "plugin": [["opencode-tokscale", {
+    "enabled": true,
+    "refreshInterval": 60,
+    "showOpenCodeOnly": true
+  }]]
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `refreshInterval` | `60` | Seconds between data refreshes |
+| `showOpenCodeOnly` | `true` | Show only opencode usage (`--opencode` flag). Set `false` for all clients |
+
+## How It Works
+
+Shells out to `tokscale models --json` with `--today`, `--week`, and `--month` flags. Parses the JSON. Renders totals in the sidebar.
+
+```
+setInterval(60s) → tokscale models --json --today --opencode --no-spinner → parse → render
+                 → tokscale models --json --week  --opencode --no-spinner → parse → render
+                 → tokscale models --json --month --opencode --no-spinner → parse → render
+```
+
+Three parallel CLI calls per refresh. tokscale processes in ~175ms thanks to its Rust core, so the sidebar stays snappy.
+
+## Features
+
+|   | What | Why it matters |
+|:---:|---|---|
+| ⏱ | **Auto-refresh** | Configurable interval, default 60 seconds |
+| 🛡 | **Graceful fallback** | No tokscale? Shows install instructions instead of crashing |
+
+## Requirements
+
+- [opencode](https://opencode.ai) with plugin support (`@opencode-ai/plugin` >= 1.4.3)
+- [tokscale](https://github.com/junhoyeo/tokscale) CLI installed and in PATH
+
+## Manual Install
+
+Skip npm. Copy the source files directly:
+
+```bash
+mkdir -p ~/.config/opencode/plugins/opencode-tokscale
+cp src/tui.tsx src/tokscale.ts src/format.ts src/types.ts \
+  ~/.config/opencode/plugins/opencode-tokscale/
+```
+
+Register the local path:
+
+```json
+{
+  "plugin": [["./plugins/opencode-tokscale/tui.tsx", { "enabled": true }]]
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/stevejkang/opencode-tokscale.git
+cd opencode-tokscale
+bun install
+```
+
+Run tests:
+
+```bash
+bun run test
+```
+
+Edit, restart opencode, see changes live.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opencode-tokscale",
+  "version": "0.0.1-rc.0",
+  "type": "module",
+  "description": "OpenCode TUI sidebar plugin displaying tokscale token usage statistics and costs",
+  "exports": {
+    "./tui": "./src/tui.tsx"
+  },
+  "files": [
+    "src/tui.tsx",
+    "src/tokscale.ts",
+    "src/types.ts",
+    "src/format.ts"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui-plugin",
+    "tokscale",
+    "token-usage"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevejkang/opencode-tokscale.git"
+  },
+  "author": "stevejkang",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.1.98",
+    "@opentui/solid": "^0.1.98",
+    "solid-js": "^1.9.12",
+    "vitest": "4.1.4"
+  }
+}

package/src/format.ts

@@ -0,0 +1,25 @@
+import type { ModelReportJson } from "./types"
+
+const currencyFormatter = new Intl.NumberFormat("en-US", {
+  style: "currency",
+  currency: "USD",
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2,
+})
+
+export function formatTokens(count: number): string {
+  if (count <= 0) return "0"
+  if (count >= 1_000_000_000) return `${(count / 1_000_000_000).toFixed(1)}B`
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}K`
+  return String(count)
+}
+
+export function formatCost(cost: number): string {
+  if (cost <= 0) return "$0.00"
+  return currencyFormatter.format(cost)
+}
+
+export function computeTotalTokens(report: ModelReportJson): number {
+  return report.totalInput + report.totalOutput + report.totalCacheRead + report.totalCacheWrite
+}

package/src/tokscale.ts

@@ -0,0 +1,80 @@
+import { execFile } from "child_process"
+import type { ModelReportJson, TimePeriod, PeriodStats } from "./types"
+import { PERIOD_FLAGS } from "./types"
+
+let cachedDetection: boolean | null = null
+
+export function resetDetectionCache(): void {
+  cachedDetection = null
+}
+
+export function detectTokscale(): Promise<boolean> {
+  if (cachedDetection !== null) return Promise.resolve(cachedDetection)
+
+  return new Promise((resolve) => {
+    execFile("which", ["tokscale"], { timeout: 5000 }, (error) => {
+      cachedDetection = !error
+      resolve(cachedDetection)
+    })
+  })
+}
+
+export function fetchPeriodStats(
+  period: TimePeriod,
+  options?: { openCodeOnly?: boolean },
+): Promise<PeriodStats> {
+  const args = ["models", "--json", PERIOD_FLAGS[period], "--no-spinner"]
+  if (options?.openCodeOnly !== false) args.push("--opencode")
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      "tokscale",
+      args,
+      { timeout: 15000, maxBuffer: 1024 * 1024 },
+      (error, stdout) => {
+        if (error) {
+          reject(new Error(`tokscale CLI failed: ${error.message}`))
+          return
+        }
+        try {
+          const report = parseModelReport(stdout as string)
+          resolve(reportToStats(report))
+        } catch (e) {
+          reject(e)
+        }
+      },
+    )
+  })
+}
+
+export function parseModelReport(stdout: string): ModelReportJson {
+  if (!stdout) throw new Error("Empty output from tokscale CLI")
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stdout)
+  } catch {
+    throw new Error(`Invalid JSON from tokscale CLI: ${stdout.slice(0, 100)}`)
+  }
+
+  const report = parsed as Record<string, unknown>
+  if (
+    typeof report.totalInput !== "number" ||
+    typeof report.totalOutput !== "number" ||
+    typeof report.totalCost !== "number"
+  ) {
+    throw new Error("Invalid tokscale report: missing required numeric fields")
+  }
+
+  return parsed as ModelReportJson
+}
+
+export function reportToStats(report: ModelReportJson): PeriodStats {
+  return {
+    totalTokens:
+      report.totalInput + report.totalOutput + report.totalCacheRead + report.totalCacheWrite,
+    totalCost: report.totalCost,
+    totalMessages: report.totalMessages,
+    fetchedAt: Date.now(),
+  }
+}

package/src/tui.tsx

@@ -0,0 +1,112 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin, TuiPluginModule, TuiSlotContext } from "@opencode-ai/plugin/tui"
+import { createSignal } from "solid-js"
+import type { TimePeriod, PeriodState, TokscalePluginOptions } from "./types"
+import { TIME_PERIODS, PERIOD_LABELS } from "./types"
+import { formatTokens, formatCost } from "./format"
+import { detectTokscale, fetchPeriodStats } from "./tokscale"
+
+const TOKSCALE_BLUE = "#0073FF"
+
+const tui: TuiPlugin = async (api, options, _meta) => {
+  const refreshInterval = ((options as TokscalePluginOptions)?.refreshInterval ?? 60) * 1000
+  const showOpenCodeOnly = (options as TokscalePluginOptions)?.showOpenCodeOnly ?? true
+
+  const signals: Record<TimePeriod, [() => PeriodState, (s: PeriodState) => void]> = {} as Record<TimePeriod, [() => PeriodState, (s: PeriodState) => void]>
+  for (const period of TIME_PERIODS) {
+    signals[period] = createSignal<PeriodState>({ status: "idle", stats: null, error: null })
+  }
+
+  const [installed, setInstalled] = createSignal<boolean | null>(null)
+
+  let refreshing = false
+  async function refresh() {
+    if (refreshing) return
+    refreshing = true
+    try {
+      const isInstalled = await detectTokscale()
+      setInstalled(isInstalled)
+      if (!isInstalled) {
+        for (const period of TIME_PERIODS) {
+          signals[period][1]({ status: "not-installed", stats: null, error: null })
+        }
+        return
+      }
+      await Promise.allSettled(
+        TIME_PERIODS.map(async (period) => {
+          const setState = signals[period][1]
+          setState({ status: "loading", stats: signals[period][0]().stats, error: null })
+          try {
+            const stats = await fetchPeriodStats(period, {
+              openCodeOnly: showOpenCodeOnly,
+            })
+            setState({ status: "success", stats, error: null })
+          } catch (e) {
+            setState({ status: "error", stats: signals[period][0]().stats, error: String(e) })
+          }
+        })
+      )
+    } finally {
+      refreshing = false
+    }
+  }
+
+  refresh()
+
+  const timer = setInterval(refresh, refreshInterval)
+  api.lifecycle.onDispose(() => clearInterval(timer))
+
+  api.slots.register({
+    order: 50,
+    slots: {
+      sidebar_content(ctx: TuiSlotContext, _props: unknown) {
+        const t = ctx.theme.current
+        const dim = t.textMuted ?? "#546E7A"
+        const fgColor = t.text ?? "#EEFFFF"
+
+        return (
+          <box flexDirection="column" marginBottom={1}>
+            <box height={1}>
+              <text fg={TOKSCALE_BLUE}><b>{"Tokscale"}</b></text>
+            </box>
+
+            {installed() === false ? (
+              <box height={1}>
+                <text fg={dim}>{"Install: npm i -g @tokscale/cli"}</text>
+              </box>
+            ) : (
+              TIME_PERIODS.map((period) => {
+                const state = signals[period][0]()
+                const label = PERIOD_LABELS[period]
+                return (
+                  <box height={1} flexDirection="row">
+                    <text fg={fgColor}>{`${label.padEnd(12)}`}</text>
+                    {state.status === "loading" && !state.stats ? (
+                      <text fg={dim}>{"..."}</text>
+                    ) : state.status === "error" && !state.stats ? (
+                      <text fg={dim}>{"err"}</text>
+                    ) : state.stats ? (
+                      <>
+                        <text fg={TOKSCALE_BLUE}>{`${formatTokens(state.stats.totalTokens).padStart(7)}`}</text>
+                        <text fg={dim}>{` ${formatCost(state.stats.totalCost).padStart(9)}`}</text>
+                      </>
+                    ) : (
+                      <text fg={dim}>{"—"}</text>
+                    )}
+                  </box>
+                )
+              })
+            )}
+          </box>
+        ) as any
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "opencode-tokscale",
+  tui,
+}
+
+export default plugin

package/src/types.ts

@@ -0,0 +1,63 @@
+export interface ModelUsageJson {
+  client: string
+  mergedClients: string | null
+  workspaceKey?: string | null
+  workspaceLabel?: string
+  model: string
+  provider: string
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  reasoning: number
+  messageCount: number
+  cost: number
+}
+
+export interface ModelReportJson {
+  groupBy: string
+  entries: ModelUsageJson[]
+  totalInput: number
+  totalOutput: number
+  totalCacheRead: number
+  totalCacheWrite: number
+  totalMessages: number
+  totalCost: number
+  processingTimeMs: number
+}
+
+export type TimePeriod = "today" | "week" | "month"
+
+export interface PeriodStats {
+  totalTokens: number
+  totalCost: number
+  totalMessages: number
+  fetchedAt: number
+}
+
+export type TokscaleStatus = "idle" | "loading" | "success" | "error" | "not-installed"
+
+export interface PeriodState {
+  status: TokscaleStatus
+  stats: PeriodStats | null
+  error: string | null
+}
+
+export interface TokscalePluginOptions {
+  refreshInterval?: number
+  showOpenCodeOnly?: boolean
+}
+
+export const PERIOD_FLAGS: Record<TimePeriod, string> = {
+  today: "--today",
+  week: "--week",
+  month: "--month",
+} as const
+
+export const PERIOD_LABELS: Record<TimePeriod, string> = {
+  today: "Today",
+  week: "This Week",
+  month: "This Month",
+} as const
+
+export const TIME_PERIODS: readonly TimePeriod[] = ["today", "week", "month"] as const