@foae/opencode-timings 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Foae
+
+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

@@ -0,0 +1,55 @@
+# opencode-timings
+
+A tiny [OpenCode](https://opencode.ai) **TUI sidebar** plugin that shows
+per-session timing — how much wall-clock the session has taken and how much of
+that was actually spent waiting on the model.
+
+It renders into the same right-hand sidebar as the Quota / MCP / LSP / Todo /
+Files panels, reading the session's messages directly from the TUI's reactive
+state. Nothing is ever injected into the message stream, so there is **zero
+context-window pollution**.
+
+```
+Timing
+ API   6m31s  54%
+ wall  12m04s
+ turns 18 · avg 21s
+ slow  1m12s
+```
+
+## Metrics
+
+| Row     | Meaning |
+|---------|---------|
+| `API`   | Total assistant inference time — the sum of `time.completed − time.created` over every completed assistant message — and its share of wall-clock. |
+| `wall`  | Span from the first to the last message timestamp. Includes the time you spend reading/typing between turns, so `API` is always a fraction of it. |
+| `turns` | Number of completed assistant messages, plus the average per-turn duration. |
+| `slow`  | The single slowest assistant message. |
+
+The panel is always shown; before the first turn its values read zero.
+
+## Install
+
+Add it to the `plugin` array of the **TUI** config that OpenCode loads
+(`~/.config/opencode/tui.json` or `tui.jsonc`) — this is a TUI plugin, so it
+belongs in `tui.json`, not `opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@foae/opencode-timings@latest"]
+}
+```
+
+OpenCode installs the plugin and its dependencies with Bun at startup. Restart
+OpenCode and open the session sidebar to see the `Timing` panel.
+
+You can also pin a version, e.g. `@foae/opencode-timings@0.1.0`.
+
+## Requirements
+
+- OpenCode `1.15.x` or newer (uses the TUI slot plugin API).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@foae/opencode-timings",
+  "version": "0.1.0",
+  "description": "OpenCode TUI sidebar panel showing per-session timing: total API/inference time, wall-clock, turns, average and slowest turn. Zero context-window pollution.",
+  "license": "MIT",
+  "author": "foae",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foae/opencode-timings.git"
+  },
+  "homepage": "https://github.com/foae/opencode-timings#readme",
+  "bugs": {
+    "url": "https://github.com/foae/opencode-timings/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "sidebar",
+    "timing",
+    "duration",
+    "metrics",
+    "session"
+  ],
+  "oc-plugin": [
+    "tui"
+  ],
+  "exports": {
+    "./tui": {
+      "default": "./src/tui.tsx"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.107",
+    "@opentui/solid": "^0.1.107",
+    "solid-js": "^1.9.12"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.14.29"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.14.29",
+    "@opencode-ai/sdk": "^1.14.29",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/src/tui.tsx

@@ -0,0 +1,170 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * opencode-timings — a TUI sidebar panel showing per-session timing.
+ *
+ * Renders into OpenCode's `sidebar_content` slot (alongside Quota / MCP / LSP /
+ * Todo / Files), reading the session's messages straight from the reactive TUI
+ * state. Nothing is injected into the message stream, so there is zero
+ * context-window pollution.
+ *
+ * Metrics (per session):
+ *   - API    total assistant inference time = sum of (time.completed - time.created)
+ *            over every completed assistant message, with its share of wall-clock.
+ *   - wall   span from the first to the last message timestamp (includes the time
+ *            you spend reading/typing between turns).
+ *   - turns  number of completed assistant messages, plus the average duration.
+ *   - slow   the single slowest assistant message.
+ *
+ * Modelled on @slkiser/opencode-quota's sidebar plugin (the reference for the
+ * sidebar_content slot mechanism on OpenCode 1.15.x).
+ */
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import type { Message } from "@opencode-ai/sdk/v2"
+import { createSignal, onCleanup } from "solid-js"
+
+const id = "opencode-timings"
+
+// Render just below Quota (order 150) and above the variable-height built-in
+// sections (MCP/LSP/Todo/Files) so the panel stays near the top of the fold.
+const SIDEBAR_ORDER = 155
+
+// Wall-clock and API time are derived purely from message timestamps, so events
+// drive updates; this interval is just a low-frequency backstop.
+const REFRESH_INTERVAL_MS = 15_000
+
+type Timing = {
+  ok: boolean
+  apiMs: number
+  wallMs: number
+  turns: number
+  avgMs: number
+  slowestMs: number
+  apiPct: number
+}
+
+const EMPTY: Timing = { ok: false, apiMs: 0, wallMs: 0, turns: 0, avgMs: 0, slowestMs: 0, apiPct: 0 }
+
+function computeTiming(messages: ReadonlyArray<Message>): Timing {
+  let apiMs = 0
+  let turns = 0
+  let slowestMs = 0
+  let minTs = Number.POSITIVE_INFINITY
+  let maxTs = 0
+
+  for (const msg of messages) {
+    const created = msg.time?.created
+    if (typeof created === "number") {
+      if (created < minTs) minTs = created
+      if (created > maxTs) maxTs = created
+    }
+    if (msg.role === "assistant") {
+      const completed = msg.time?.completed
+      if (typeof completed === "number") {
+        if (completed > maxTs) maxTs = completed
+        const dur = completed - (typeof created === "number" ? created : completed)
+        if (dur > 0) {
+          apiMs += dur
+          turns += 1
+          if (dur > slowestMs) slowestMs = dur
+        }
+      }
+    }
+  }
+
+  if (turns === 0) return EMPTY
+  const wallMs = minTs === Number.POSITIVE_INFINITY ? 0 : Math.max(0, maxTs - minTs)
+  return {
+    ok: true,
+    apiMs,
+    wallMs,
+    turns,
+    avgMs: apiMs / turns,
+    slowestMs,
+    apiPct: wallMs > 0 ? Math.round((apiMs / wallMs) * 100) : 0,
+  }
+}
+
+/** Compact, sidebar-friendly duration: "42s", "6m31s", "1h02m". */
+function fmtDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) ms = 0
+  const totalSec = Math.round(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const totalMin = Math.floor(totalSec / 60)
+  if (totalMin < 60) return `${totalMin}m${String(totalSec % 60).padStart(2, "0")}s`
+  const hours = Math.floor(totalMin / 60)
+  return `${hours}h${String(totalMin % 60).padStart(2, "0")}m`
+}
+
+function SidebarTimingView(props: { api: TuiPluginApi; sessionID: string }) {
+  const read = (): Timing => computeTiming(props.api.state.session.messages(props.sessionID))
+  const [timing, setTiming] = createSignal<Timing>(read())
+  const refresh = () => setTiming(read())
+
+  // TUI/session state can hydrate asynchronously after mount or a session
+  // switch, so recompute a few times early to recover from empty first reads.
+  const recovery = [setTimeout(refresh, 400), setTimeout(refresh, 1500), setTimeout(refresh, 4000)]
+  const interval = setInterval(refresh, REFRESH_INTERVAL_MS)
+
+  const unsubscribers = [
+    props.api.event.on("message.updated", (event) => {
+      if (event.properties?.info?.sessionID === props.sessionID) refresh()
+    }),
+    props.api.event.on("message.removed", (event) => {
+      if (event.properties?.sessionID === props.sessionID) refresh()
+    }),
+    props.api.event.on("session.updated", (event) => {
+      if (event.properties?.info?.id === props.sessionID) refresh()
+    }),
+    props.api.event.on("session.idle", (event) => {
+      if (event.properties?.sessionID === props.sessionID) refresh()
+    }),
+  ]
+
+  onCleanup(() => {
+    for (const timer of recovery) clearTimeout(timer)
+    clearInterval(interval)
+    for (const unsubscribe of unsubscribers) unsubscribe()
+  })
+
+  const lines = (): string[] => {
+    const t = timing()
+    return [
+      `API   ${fmtDuration(t.apiMs)}  ${t.apiPct}%`,
+      `wall  ${fmtDuration(t.wallMs)}`,
+      `turns ${t.turns} · avg ${fmtDuration(t.avgMs)}`,
+      `slow  ${fmtDuration(t.slowestMs)}`,
+    ]
+  }
+
+  // Always rendered (even before the first turn, showing zeros) so the panel
+  // is a permanent fixture of the sidebar.
+  return (
+    <box gap={0}>
+      <text fg={props.api.theme.current.text}>
+        <b>Timing</b>
+      </text>
+      <box gap={0}>
+        {lines().map((line) => (
+          <text fg={props.api.theme.current.textMuted} wrapMode="none">
+            {line || " "}
+          </text>
+        ))}
+      </box>
+    </box>
+  )
+}
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    order: SIDEBAR_ORDER,
+    slots: {
+      sidebar_content(_ctx, props: { session_id: string }) {
+        return <SidebarTimingView api={api} sessionID={props.session_id} />
+      },
+    },
+  })
+}
+
+const pluginModule: TuiPluginModule & { id: string } = { id, tui }
+
+export default pluginModule