opencode-tokscope 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +37 -78
  2. package/dist/tui.js +1766 -326
  3. package/package.json +23 -5
package/README.md CHANGED
@@ -1,103 +1,62 @@
1
1
  # opencode-tokscope
2
2
 
3
- An OpenCode v2 TUI plugin answering: **which models and providers are fastest in my actual usage?** and **is a model/provider getting faster or slower over time?**
3
+ [![npm version](https://img.shields.io/npm/v/opencode-tokscope.svg)](https://www.npmjs.com/package/opencode-tokscope)
4
+ [![license](https://img.shields.io/npm/l/opencode-tokscope.svg)](https://github.com/mihaellenic/opencode-tokscope/blob/main/LICENSE)
5
+ [![made for OpenCode](https://img.shields.io/badge/made%20for-OpenCode%20V2-1024D3)](https://opencode.ai/docs/plugins/)
4
6
 
5
- Opens a full-screen `/tokscope` page with a median tok/s comparison table (one row per model + provider) and a per-model daily median trend, and adds a compact summary to the session sidebar.
7
+ **Which models and providers are fastest in your actual OpenCode usage? And are they getting faster or slower?**
6
8
 
7
- ## Sidebar
9
+ Tokscope is an OpenCode V2 terminal UI plugin with:
8
10
 
9
- The bottom of the session sidebar shows the three fastest model/provider pairs from a rolling 24-hour window across **all projects** on the connected instance (not just the current session or project). A pair needs at least three measured requests inside the window to appear; one or two qualifying pairs show one or two rows, and none shows `No models with 3+ calls in 24h.`
11
+ - A full-screen `/tokscope` page comparing median tokens per second for each model/provider pair.
12
+ - A daily median trend for the selected pair, with project, time-range, and reasoning-setting filters.
13
+ - A clickable sidebar summary of the fastest pairs over the last 24 hours.
10
14
 
11
- Rows show the full model name and as much of the provider name as fits, followed by the integer median tok/s. Speeds are right-aligned under the `tok/s` heading; per-entry call counts and repeated units are omitted. The scope and window are fixed — the sidebar does not follow the full page's filters.
15
+ ![Real OpenCode session with the Tokscope widget in the sidebar: fastest model/provider pairs over the last 24 hours](https://raw.githubusercontent.com/mihaellenic/opencode-tokscope/main/docs/images/tokscope-sidebar.png)
12
16
 
13
- Click anywhere in the widget to open the full page. The widget refreshes when a model step completes and once a minute while visible; after a read failure the last successful rows stay on screen marked `(stale)`. The sidebar has no shortcut of its own — `/tokscope` and the command palette remain the keyboard entry points.
14
-
15
- ## Metric
16
-
17
- One sample = one completed model request (an assistant step), including main-agent, subagent, and background activity.
18
-
19
- ```
20
- tok/s = (tokens.output + tokens.reasoning) / ((time.streamed - time.created) / 1000)
21
- ```
22
-
23
- - Matches OpenCode's native TUI throughput semantics: `time.streamed` is when the provider response body ended, so tool settlement time is excluded.
24
- - Input and cache tokens never count toward generated-token throughput.
25
- - Headline per model/provider is the **median of individual request rates** — not total tokens ÷ total duration, and not an average.
26
- - Measured: completed, no error, `time.streamed` present, positive duration, and `output + reasoning > 0`.
27
- - Unavailable: completed requests missing that data (older history). They appear as `unavailable` with `0` calls after measured rows, and are counted in the coverage line — never shown as `0.0 tok/s`.
28
- - Failed, cancelled, and in-progress requests are excluded entirely.
29
-
30
- Historical sessions are read through the running OpenCode server, so requests made before installing the plugin are included wherever the recorded data supports the metric. Daily trends bucket by local calendar day using the day the request completed; days without measurements are gaps, never zeros.
17
+ ![Model/provider comparison and daily trend — synthetic mockup](https://raw.githubusercontent.com/mihaellenic/opencode-tokscope/main/docs/images/tokscope-overview.png)
31
18
 
32
19
  ## Install
33
20
 
34
- Requires an OpenCode V2 TUI. The packaged plugin is built against the OpenCode 2.1.2 API and development pins; the actual npm artifact was runtime-validated on OpenCode 2.1.4, while 2.1.2 was historically tested. Other 2.x versions are untested, and V1 is not supported.
35
-
36
- The one-command install:
21
+ Requires **OpenCode V2 TUI**.
37
22
 
38
- ```bash
23
+ ```sh
39
24
  opencode plugin add opencode-tokscope
40
25
  ```
41
26
 
42
- `plugin add` classifies the package as a TUI plugin (verified against the released OpenCode 2.1.4 CLI) and records it in `~/.config/opencode/cli.json` for you. Older 2.x CLIs whose `plugin add` predates TUI-class packages do not support this form.
43
-
44
- Only if `opencode plugin add` does not work for some reason, add the plugin manually to the `plugins` array in `~/.config/opencode/cli.json`. Add or extend only that key; keep every unrelated setting already in the file. A minimal file looks like this:
45
-
46
- ```json
47
- {
48
- "$schema": "https://opencode.ai/v2/cli.json",
49
- "plugins": ["opencode-tokscope"]
50
- }
51
- ```
52
-
53
- To pin the first release instead of following the latest published version, use `opencode plugin add opencode-tokscope@0.1.0`, or put `"opencode-tokscope@0.1.0"` in the manual array entry.
27
+ ## Use
54
28
 
55
- OpenCode loads installed plugins automatically. Run `/tokscope`, or open the palette (`ctrl+p`) and pick "Tokscope". If the command does not appear, run `/reload`; restart OpenCode only when you changed dependencies that it does not watch for reloads.
29
+ Run `/tokscope`, or press `Ctrl+P` and select **Tokscope**.
56
30
 
57
- ## Local development (Bun)
31
+ The page opens with **all projects · last 30 days · all reasoning settings**. Active filters and measured/unavailable coverage remain visible.
58
32
 
59
- Consumers install the published package; they do not need Bun or a build step. The npm artifact ships prebuilt JavaScript. The following setup is only for working on this repository.
60
-
61
- Requires Bun.
62
-
63
- ```bash
64
- bun install
65
- bun run build
66
- ```
67
-
68
- `Bun.build` with the Solid transform from `@opentui/solid/bun-plugin` produces `dist/tui.js`. Host-provided modules stay **external** so OpenCode's runtime-plugin transform binds them to the TUI's own instances: `effect`, `@opencode/plugin` (and subpaths), `solid-js`, `@opentui/core`, `@opentui/solid`, `@opentui/keymap` (and subpaths). Bundling those produces a second Solid/OpenTUI runtime and the page fails with `No renderer found`.
33
+ | Key | Action |
34
+ | --- | --- |
35
+ | `↑` / `↓` or `k` / `j` | Select a model/provider pair |
36
+ | `←` / `→` | Select a day in its trend |
37
+ | `s` | Choose current project or all projects |
38
+ | `t` | Choose last 7 / 30 / 90 days or all history |
39
+ | `r` | Choose all / a recorded reasoning setting / unknown |
40
+ | `Esc` | Return to the previous screen |
41
+ | `Enter` | Retry after a read error |
69
42
 
70
- Development pins match the tested host (`opencode v2.1.2`): `@opencode/plugin@2.1.2`, `@opencode/client@2.1.2`, `@opentui/*@0.6.6`, `solid-js@1.9.15`.
43
+ **Sidebar:** shows up to three fastest pairs across **all projects on the connected instance**, each requiring at least **three measured calls in the rolling 24-hour window**. Click anywhere in the widget to open the page. It refreshes after a model step completes and once a minute while visible. Read failures retain the last successful rows marked `(stale)`; no qualifying pairs shows `No models with 3+ calls in 24h.`
71
44
 
72
- For local discovery, symlink the checkout into OpenCode's plugin directory:
45
+ ## What tok/s means
73
46
 
74
- ```bash
75
- mkdir -p ~/.config/opencode/plugins
76
- ln -sfn /path/to/opencode-tokscope ~/.config/opencode/plugins/opencode-tokscope
77
- ```
47
+ One sample is one completed model request (assistant step), including main-agent, subagent, and background activity:
78
48
 
79
- OpenCode picks up the link automatically where it can; if it does not, run `/reload`. A full restart is only needed when development dependencies outside OpenCode's watch set change. Rebuild and reload after source edits.
80
-
81
- ```bash
82
- bun test # unit tests (metric, harvest, aggregation, chart, state)
83
- bun run typecheck # tsc --noEmit (Bun.build strips types, so this is the type gate)
84
- bun run build # rebuild dist/tui.js, then reload OpenCode
49
+ ```text
50
+ tok/s = (tokens.output + tokens.reasoning) / ((time.streamed - time.created) / 1000)
85
51
  ```
86
52
 
87
- ## Usage
88
-
89
- | Key | Action |
90
- | --- | --- |
91
- | `↑` / `↓` (or `k` / `j`) | Move row selection |
92
- | `←` / `→` | Move day selection in the trend |
93
- | `s` | Scope: current project / all projects |
94
- | `t` | Time range: last 7 / 30 / 90 days, all history |
95
- | `r` | Reasoning setting: all / a recorded setting / unknown |
96
- | `esc` | Return to the previous screen |
97
- | `enter` | Retry after a read error |
98
-
99
- Defaults on open: all projects, last 30 days, all reasoning settings combined. Current project remains selectable. Header and footer always show the active filters and coverage (`N measured calls; M unavailable`).
53
+ - Comparisons use the **median of individual request rates**, not an average or total tokens divided by total duration.
54
+ - The interval ends when the provider response body ends, excluding tool settlement time. Input and cache tokens do not count.
55
+ - Measurements require completion without error, a recorded stream end, positive duration, and positive generated tokens. Failed, cancelled, and in-progress requests are excluded.
56
+ - Completed requests without usable data count as **unavailable**, never zero throughput. Pairs with only unavailable data appear after measured rows with `0` measured calls.
57
+ - Existing history is read through the connected OpenCode server, including requests made before installation when the recorded data supports measurement. Daily trends use the local calendar day of completion; missing days are gaps, not zeros.
100
58
 
101
- ## License
59
+ ## Project links
102
60
 
103
- MIT. See [LICENSE](LICENSE).
61
+ - [Contributing and local development](https://github.com/mihaellenic/opencode-tokscope/blob/main/CONTRIBUTING.md)
62
+ - [MIT license](https://github.com/mihaellenic/opencode-tokscope/blob/main/LICENSE)