opencode-tweaks 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FURYMOB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# opencode-tweaks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/furymob-git/opencode-tweaks/actions/workflows/ci.yml/badge.svg)](https://github.com/furymob-git/opencode-tweaks/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Settings and small interface improvements for [OpenCode](https://opencode.ai), collected in one place.
+
+OpenCode is already comfortable out of the box. This plugin is for the details you may still want to tune: a command
+that is missing, a keybinding that does not fit your workflow, a behavior you would rather switch off. Every tweak is
+optional, and the defaults stay exactly where they are.
+
+## Status
+
+Early development. The `/tweaks` menu and the OpenCode Go quota sidebar are in place. Both the tweak list and the
+configuration format may change before the first stable release.
+
+## Principles
+
+- **Sensible defaults.** Tweaks are on out of the box, tuned to the setup that works best day to day. Every one has a
+  switch in `/tweaks` when you want OpenCode untouched.
+- **Native first.** If OpenCode already handles something well, this plugin does not replace it.
+- **Public API only.** No forks, patches, or private imports. Everything goes through `@opencode/plugin`.
+- **Small surface.** Each tweak is isolated and documented, so you can see exactly what it changes.
+
+## Requirements
+
+- OpenCode 2.x
+- Node.js 24 or newer for local development
+
+## Install
+
+```sh
+opencode plugin add opencode-tweaks
+```
+
+Or let OpenCode install and verify it for you. Paste this prompt into a session:
+
+```text
+Install the opencode-tweaks plugin on this machine.
+
+- Run `opencode --version` first and stop with a clear message if it is not 2.x.
+- Run `opencode plugin add opencode-tweaks`.
+- Run `opencode plugin list` and confirm opencode-tweaks is registered.
+- Tell me the plugin version, the config file that changed, and anything I need to restart.
+- Do not edit my existing settings or plugin options.
+```
+
+To add it by hand, put it in the `plugins` list in `opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-tweaks"]
+}
+```
+
+To follow the source instead, point the same list at a local checkout, such as `"../opencode-tweaks"`. Relative paths
+resolve from the config file that contains the entry and must point at a directory.
+
+## Settings
+
+Run `/tweaks` to open the settings menu. It mirrors OpenCode's own settings dialog: the same theme, grouped rows, search
+field, and footer hints. The tweak list opens first; selecting one shows its settings. Boolean settings toggle in place;
+other settings cycle through their values with `enter` or `←`/`→`. Press `ctrl+r` to reset the selected setting.
+
+The command also appears in the palette under `Tweaks`. Its id is `opencode-tweaks.tweaks` if you want to bind a key in
+`cli.json`.
+
+Values are resolved in this order:
+
+1. a value changed from `/tweaks` and stored locally by the plugin
+2. an option in `opencode.json`
+3. the default in the tweak definition
+
+Options are useful when you want the same configuration on several machines:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-tweaks",
+      "options": {
+        "quota": {
+          "enabled": true,
+          "barWidth": 30
+        }
+      }
+    }
+  ]
+}
+```
+
+Resetting a setting drops the local value, so the option or default applies again.
+
+## Tweaks
+
+| Tweak    | What it does                                                      | Default |
+| -------- | ----------------------------------------------------------------- | ------- |
+| `quota`  | Provider quota, reset times, and a daily spending budget.         | On      |
+| `tokens` | Token and cost usage per turn, plus session totals at the bottom. | On      |
+
+### Quota
+
+Quota shows the OpenCode Go limits for the 5h, 7d, and 30d windows. It uses the active OpenCode Console sign-in when
+there is one, then an `opencode-go` API key. Sign in with `opencode auth login opencode` or
+`opencode auth login opencode-go` before enabling the tweak.
+
+The panel refreshes every two minutes, and a failed read retries after twenty seconds and keeps the last rows. Click the
+`Quota` header to collapse or expand the rows. Bar width defaults to `auto`, which uses the space the sidebar leaves
+after the percent and reset columns. A fixed width is available from `/tweaks`.
+
+`Percent decimals` chooses 0, 1, or 2 decimals for every percentage, the `day` row included. The Console endpoints
+publish a finer share than a whole percent, so the figures move between points instead of jumping a whole one; a source
+that only reports whole percents shows the same value either way.
+
+The provider name sits on the `Quota` line by default and can be aligned left, center, or right. Turning
+`One tab per provider` off gives it a line of its own, above the rows that collapse underneath.
+
+`Current provider only` is on by default. Each quota source is registered on the server under the provider ID the model
+catalog uses, so the panel names no provider itself and follows the model in use: it appears for a provider whose quota
+the plugin can read, and stays hidden for one that publishes none. Turn the setting off to show every quota the plugin
+knows at once. OpenCode Go is the only source today; adding another is a reader and one entry in the registry.
+
+`Daily budget` adds a `day` row under the longest window: the share of that quota set aside for today, spread over the
+workdays left before it resets. The bar starts full each morning and empties as the provider reports less quota, so you
+see how much of today's share is left. It takes the theme accent color and turns orange near the end, then red once the
+share is spent. The figures are frozen at the first reading of the day, so the bar only moves when quota is used, not
+on every refresh.
+
+`Reserve` keeps a percentage of the window out of the daily budget, so the month does not end at zero. The `Workdays`
+settings choose which weekdays count; every day counts by default, and a day left off gets no budget and shows `rest` on
+the row. The budget resets at local midnight, and a changed provider reset or workday pattern starts a fresh one.
+
+### Tokens
+
+Tokens shows two token counts and, optionally, their cost. Each has its own toggle.
+
+`Turn tokens` adds what the latest finished turn spent to its `tok/s` line: `12.3K tok · 62.2 tok/s`. OpenCode draws
+that line itself and publishes no slot inside it, so the tweak splices the value into the line's text node and repairs
+the splice while a turn runs. That placement is best effort and may lag or break when OpenCode changes the line. When the
+splice is not available the count stays out of the line rather than moving elsewhere.
+
+The line belongs to the turn that finished above it, so each line keeps its own figures: while the next turn runs, the
+previous line still shows the previous turn's numbers rather than the running one's. When a turn finishes, its line
+receives its figures and the older lines keep theirs.
+
+`First token time` controls the host's own `1.7s ttft` figure at the end of that line: it is off by default, so the
+span is removed and `tok/s` stays alone. Turning it on restores the host's figure.
+
+`Turn cost` adds that turn's cost after the throughput figure: `62.2 tok/s · $0.0042`.
+
+`Session tokens` adds the session's total usage to the bottom status line, before the host's context figure:
+`1 shell · 790.6K tok total · $0.91 · 115K (29%)`. It reads the counters the session itself keeps, so
+the number stays exact even when the transcript has only loaded its latest messages. The figures follow the shell
+indicator when one is running and otherwise open the context text, so the order stays shell, total, session cost,
+context. OpenCode draws those texts itself and publishes no slot inside them, so the figures are spliced in and
+repaired while the line changes; when the splice is not available the figures stay out of the line rather than
+moving elsewhere.
+
+`Token count` picks what the two numbers add up. `Generated only` is the default: it keeps just what the model wrote.
+`New tokens` adds prompt, completion, reasoning, and cache writes, without cache reads, because a turn re-reads the
+whole context at every step and those reads would dwarf everything else. `Everything` matches the counters `/stats`
+reports, cache reads included. `Include subagents` is on by default, so the session totals cover the whole session tree
+instead of only the session on screen; the per-turn count always stays on the session on screen, because a prompt
+belongs to it. `Token format` switches between compact counts such as `12.4K` and every digit such as `12,431`.
+
+Costs come from what the provider reports, so a free plan shows `$0.00`. `Cost decimals` controls the decimals:
+`Auto` keeps two decimals and grows until the first significant digit shows (`$0.004`), while a fixed choice always
+keeps that many (`$0.0042`).
+
+`Estimate cost` fills in a price the provider did not report, using the model's list price from the same catalog
+OpenCode already synced: prompt, completion, reasoning billed as output, and cache traffic, each at its own rate. A
+provider that reports a price always wins, and a session that changed model is estimated with the model it ended on, so
+treat the figure as an estimate. This is what makes the OpenCode Go monthly credit readable: the plan reports `$0.00`
+per turn, and the estimate follows the API rates instead. Costs use the raw counters whatever `Token count` says.
+
+## Development
+
+```sh
+npm install
+npm run check
+```
+
+`npm run check` runs the type checker, the linter, and the tests. `npm run format` applies the formatter.
+
+OpenCode loads the package from `src`, so there is no build step. To test changes, configure the checkout as a local
+plugin (see Install) and let the config watcher reload it. If a change is not picked up, run `opencode service restart`.
+
+```text
+src/
+  index.ts          server entry: quota RPC registration
+  rpc.ts            typed RPC contract
+  quota/
+    service.ts      credential lookup and quota fetch
+    parse.ts        provider response parsing
+    format.ts       percents, reset times, and bars
+  tui.tsx           terminal entry: command and sidebar slot
+  tweaks/
+    types.ts        settings schema and validation
+    registry.ts     list of tweaks
+    settings.ts     stored, config, and default resolution
+    menu.ts         /tweaks entry
+    menu-dialog.tsx reactive settings dialog
+    menu-model.ts   filtering and selection helpers
+    quota.ts        quota tweak definition
+    quota-panel.tsx sidebar quota panel
+    tokens.ts       tokens tweak definition
+    token-slots.tsx inline splice driver and status line
+    token-inject.ts splice into the host's tok/s line
+    tokens-model.ts token sum and formatting
+```
+
+## Contributing
+
+Tweaks should stay small, opt-in, and built on the public plugin API. If something can be done with normal OpenCode
+configuration, it does not belong here. Open an issue before starting on anything substantial.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch model, commit format, code rules, and release process.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,64 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-tweaks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Opt-in settings and small interface improvements for OpenCode.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "author": "FURYMOB",
+  "homepage": "https://github.com/furymob-git/opencode-tweaks#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/furymob-git/opencode-tweaks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/furymob-git/opencode-tweaks/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "settings",
+    "quota",
+    "tokens"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./rpc": "./src/rpc.ts",
+    "./tui": "./src/tui.tsx"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm test"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.2.7"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.8.1",
+    "@opentui/solid": ">=0.8.1",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.7",
+    "@opentui/core": "^0.8.4",
+    "@opentui/solid": "^0.8.4",
+    "@types/node": "^24",
+    "solid-js": "^1.9.19",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import { Plugin } from "@opencode/plugin"
+import { readQuotas } from "./quota/service"
+import { Quota } from "./rpc"
+
+export default Plugin.define({
+  id: "opencode-tweaks",
+  async setup(context) {
+    const registration = await context.rpc.register(Quota, {
+      snapshot: async (input, call) => {
+        // JSON Schema methods do not infer their input, so the shape is cast here.
+        const { providerID } = input as { providerID?: string }
+        return { snapshots: await readQuotas(context, providerID, call.signal) }
+      },
+    })
+
+    return async () => {
+      await registration.dispose()
+    }
+  },
+})

package/src/quota/format.ts

@@ -0,0 +1,97 @@
+export type QuotaLevel = "good" | "warning" | "low"
+
+const MINUTE = 60_000
+
+/**
+ * One decimal only when the percent has one: "98%", "99.2%". Passing
+ * `decimals` keeps that many instead, so the column can show the finer share a
+ * provider publishes.
+ */
+export function formatPercent(value: number, decimals?: number): string {
+  const clamped = Math.max(0, Math.min(100, value))
+
+  if (decimals !== undefined) {
+    const fixed = Math.max(0, Math.min(2, Math.round(decimals)))
+    if (fixed === 0) return `${Math.round(clamped)}%`
+    const factor = 10 ** fixed
+    return `${(Math.round(clamped * factor) / factor).toFixed(fixed)}%`
+  }
+
+  const rounded = Math.round(clamped * 10) / 10
+  return Number.isInteger(rounded) ? `${rounded}%` : `${rounded.toFixed(1)}%`
+}
+
+/**
+ * The compact reset style from the sidebar: "42m", "4h 9m", "2d 23h", "29d 14h".
+ * Minutes stay visible under a day, and days always carry their hours so the
+ * column keeps the same shape.
+ */
+export function formatReset(iso: string, now: number): string {
+  const time = Date.parse(iso)
+  if (!Number.isFinite(time) || time <= now) return "now"
+
+  const minutes = Math.ceil((time - now) / MINUTE)
+  if (minutes < 60) return `${minutes}m`
+
+  const totalHours = Math.floor(minutes / 60)
+  const days = Math.floor(totalHours / 24)
+
+  if (days === 0) {
+    const rest = minutes % 60
+    return rest === 0 ? `${totalHours}h` : `${totalHours}h ${rest}m`
+  }
+
+  const hours = totalHours % 24
+  return hours === 0 ? `${days}d` : `${days}d ${hours}h`
+}
+
+/** Filled and empty cells for a line bar. The caller colors each part. */
+export function barParts(percent: number, width: number): { filled: string; empty: string } {
+  const cells = Math.max(0, Math.floor(width))
+  const clamped = Math.max(0, Math.min(100, percent))
+  const filled = Math.round((clamped / 100) * cells)
+  return {
+    filled: "━".repeat(filled),
+    empty: "─".repeat(Math.max(0, cells - filled)),
+  }
+}
+
+/** Plenty left, getting low, or almost out. */
+export function levelOf(percentRemaining: number): QuotaLevel {
+  const left = Math.max(0, Math.min(100, percentRemaining))
+  if (left < 20) return "low"
+  return left < 50 ? "warning" : "good"
+}
+
+function messageOf(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null || !("message" in value)) return undefined
+  const message = (value as { message: unknown }).message
+  return typeof message === "string" ? message : undefined
+}
+
+/**
+ * Readable text for anything thrown. The RPC client rejects with plain objects
+ * such as `{ type, message }` rather than `Error` instances, so `String(error)`
+ * would show "[object Object]" in the panel.
+ */
+export function errorText(error: unknown): string {
+  const message =
+    error instanceof Error
+      ? error.message
+      : (messageOf(error) ?? (typeof error === "string" ? error : describe(error)))
+
+  return message.trim().slice(0, 160)
+}
+
+function describe(value: unknown): string {
+  if (value === undefined || value === null) return "Unknown error"
+
+  try {
+    const json = JSON.stringify(value)
+    if (typeof json === "string" && json.length > 2) return json
+  } catch {
+    // Fall back to the default string conversion below.
+  }
+
+  return String(value)
+}

package/src/quota/pace.ts

@@ -0,0 +1,180 @@
+import type { QuotaWindowKey } from "../rpc"
+
+/**
+ * The longest window is the one a daily budget is planned on. Its nominal
+ * length is enough to choose it, because the reset date alone cannot tell a
+ * 5h window that just started from a 30d one that is about to reset.
+ */
+const WINDOW_DAYS: Readonly<Record<QuotaWindowKey, number>> = {
+  "5h": 5 / 24,
+  "7d": 7,
+  "30d": 30,
+}
+
+export interface PaceWindow {
+  readonly key: QuotaWindowKey
+  readonly percentRemaining: number
+  readonly percentRemainingExact?: number
+  readonly resetsAt: string
+}
+
+/**
+ * The share to pace with: the provider's exact figure when it publishes one, so
+ * the daily bar moves with real spending instead of a whole percent at a time.
+ */
+export function exactRemaining(window: PaceWindow): number {
+  return window.percentRemainingExact ?? window.percentRemaining
+}
+
+/**
+ * The window whose quota is spread over the days: the 30d one when the provider
+ * publishes it, the 7d one otherwise, and so on.
+ */
+export function longestWindow<Window extends PaceWindow>(
+  windows: readonly Window[],
+): Window | undefined {
+  let best: Window | undefined
+  for (const window of windows) {
+    if (!best || WINDOW_DAYS[window.key] > WINDOW_DAYS[best.key]) best = window
+  }
+  return best
+}
+
+/** Local calendar day as `2026-11-13`: the budget resets with it. */
+export function dayKey(time: number): string {
+  const date = new Date(time)
+  const month = String(date.getMonth() + 1).padStart(2, "0")
+  const day = String(date.getDate()).padStart(2, "0")
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+/** Local midnight that follows `time`, when today's budget is replaced. */
+export function endOfDay(time: number): number {
+  const date = new Date(time)
+  date.setHours(24, 0, 0, 0)
+  return date.getTime()
+}
+
+/** The weekday a timestamp falls on, with Sunday at index 0 like `Date`. */
+export function weekdayOf(time: number): number {
+  return new Date(time).getDay()
+}
+
+/**
+ * How many selected weekdays are left before the window resets, today
+ * included when it is a workday. The reset day counts even when the reset
+ * happens early, because that morning still had a budget.
+ */
+export function workdaysUntil(
+  time: number,
+  resetsAt: string,
+  workdays: readonly boolean[],
+): number {
+  const reset = Date.parse(resetsAt)
+  if (!Number.isFinite(reset) || reset <= time) return 0
+
+  const cursor = new Date(time)
+  cursor.setHours(0, 0, 0, 0)
+  const end = new Date(reset)
+  end.setHours(0, 0, 0, 0)
+
+  let count = 0
+  let guard = 0
+  // A window can never span more than a year, so the guard only stops a
+  // malformed reset date from looping.
+  while (cursor.getTime() <= end.getTime() && guard < 400) {
+    if (workdays[cursor.getDay()] === true) count += 1
+    cursor.setDate(cursor.getDate() + 1)
+    guard += 1
+  }
+  return count
+}
+
+/** Percent of the window that can be spent on each remaining workday. */
+export function dailyAllowance(
+  percentRemaining: number,
+  reserve: number,
+  workdays: number,
+): number {
+  const spendable = Math.max(0, clamp(percentRemaining) - Math.max(0, reserve))
+  if (workdays <= 0) return 0
+  return spendable / workdays
+}
+
+/** What identifies a budget day, so a changed setting starts a new baseline. */
+export function paceSignature(workdays: readonly boolean[], reserve: number): string {
+  return `${workdays.map((day) => (day ? "1" : "0")).join("")}:${reserve}`
+}
+
+/**
+ * The baseline frozen at the first reading of a budget day. Keeping the start
+ * and the allowance still means the bar only moves when quota is spent, instead
+ * of shrinking every time the panel reads a lower percentage.
+ */
+export interface PaceEntry {
+  readonly day: string
+  readonly resetsAt: string
+  readonly signature: string
+  readonly start: number
+  readonly allowance: number
+}
+
+export function isCurrent(
+  entry: PaceEntry | undefined,
+  day: string,
+  resetsAt: string,
+  signature: string,
+): boolean {
+  return (
+    entry !== undefined &&
+    entry.day === day &&
+    entry.resetsAt === resetsAt &&
+    entry.signature === signature
+  )
+}
+
+export function startPace(
+  percentRemaining: number,
+  day: string,
+  resetsAt: string,
+  signature: string,
+  workdays: readonly boolean[],
+  reserve: number,
+  now: number,
+): PaceEntry {
+  const restDay = workdays[weekdayOf(now)] !== true
+  const allowance = restDay
+    ? 0
+    : dailyAllowance(percentRemaining, reserve, workdaysUntil(now, resetsAt, workdays))
+
+  return {
+    day,
+    resetsAt,
+    signature,
+    start: clamp(percentRemaining),
+    allowance,
+  }
+}
+
+export interface PaceProgress {
+  readonly allowance: number
+  readonly spent: number
+  readonly left: number
+  /** Share of the day's allowance that is left, from 0 to 100. */
+  readonly ratio: number
+}
+
+export function paceProgress(entry: PaceEntry, percentRemaining: number): PaceProgress {
+  const spent = Math.max(0, entry.start - clamp(percentRemaining))
+  const left = Math.max(0, entry.allowance - spent)
+  const ratio = entry.allowance > 0 ? clamp((left / entry.allowance) * 100) : 0
+  return { allowance: entry.allowance, spent, left, ratio }
+}
+
+export function isWorkday(time: number, workdays: readonly boolean[]): boolean {
+  return workdays[weekdayOf(time)] === true
+}
+
+function clamp(value: number): number {
+  return Math.max(0, Math.min(100, value))
+}