opencode-how-much

在 opencode 侧边栏实时展示当前会话的累计 token 用量和上下文窗口占用。

效果

侧边栏内容区顶部（Context 面板上方）显示一个 Tokens 面板：

Tokens
in  1.23m (cache 450k · hit 36%)
out 45.7k (think 12.3k)
ctx 61.5k / 200k (31%)

• in：当前会话累计输入 token（包含缓存 token，不会重复计算）
• out：当前会话累计输出 token（包含思考/reasoning token，不会重复计算）
• cache / hit 为细分信息，便于核对
• hit：缓存命中率 = 缓存读取 token / 总输入 token（读取 + 写入 + 非缓存），会话累计口径
• think：思考 token 数，仅在 provider 上报了 reasoning 拆分时显示（Anthropic、opencode zen 网关等不拆分，此时思考已包含在 out 里，不显示避免误导）
• ctx：当前上下文窗口占用（最近一次请求的输入 + 输出）/ 模型上下文窗口上限，占用 ≥80% 变黄、≥95% 变红

自动刷新说明（重要）

opencode v1.18.x 的外部 TUI 插件渲染一次后不会响应式重绘（内置插件如 Context 因为编译进宿主所以可以）。为了让面板自动更新，本插件每 3 秒轮询一次会话消息状态，检测到数值变化时通过 session.sidebar.toggle 命令快速开关侧栏触发重挂载（净操作保持侧栏开/关状态不变，实测无闪屏）。

因此：

• 侧栏打开、切换会话时面板立即正确显示
• 新消息/流式响应完成后 3 秒内自动刷新
• 侧栏关闭时不做任何操作，不会干扰手动开关

已知取舍：刷新会重建整个侧栏，如果此时侧栏内容较多或你滚动到了下方，滚动位置可能重置。

安装

要求 opencode v1.4.3+（TUI 插件的 sidebar slot 能力），已在 v1.18.21 验证。

从 npm 安装（推荐，发布后）

opencode plugin opencode-how-much          # 当前项目
opencode plugin -g opencode-how-much       # 全局

也可以在 TUI 内安装：ctrl+p 打开命令面板 → Plugins → shift+i 输入包名（tab 切换 本地/全局 作用域）。

项目级（本仓库开发模式）

本仓库的 .opencode/tui.json 已注册本地文件 ../tui.tsx。在此目录下启动 opencode，侧边栏（Ctrl+X B）即可看到。

全局使用（所有项目）

在 ~/.config/opencode/tui.json 中注册：

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["/Users/bingxian/projects/opencode-how-much/tui.tsx"]
}

改完配置需要退出并重启 opencode 生效。

发布到 npm

npm pack                 # 预览发布内容（仅 tui.tsx / package.json / README.md）
npm publish              # 首次发布
npm version patch && npm publish   # 后续版本

发布前确保 package.json 满足 opencode 的 TUI 插件约定：

• exports["./tui"] 指向插件模块（默认导出 { id, tui }，且不能导出 server）
• engines.opencode 声明兼容的 opencode 版本范围
• 运行期依赖（solid-js、@opentui/solid、@opencode-ai/plugin）放在 dependencies，会被随包安装

使用者无需源码，直接 opencode plugin opencode-how-much 安装。卸载/禁用：暂无 CLI 卸载命令，可在 tui.json 中删除对应条目，或用 plugin_enabled 按插件 id 禁用：

{
  "plugin_enabled": { "opencode-how-much": false }
}

Token 计算口径

opencode 持久化的每一条 assistant 消息的 tokens 是互不重叠的细分字段：

| 字段 | 含义 | | --- | --- | | tokens.input | 非缓存的输入 token（不含缓存） | | tokens.cache.read/write | 缓存读 / 缓存写的输入 token | | tokens.output | 可见输出 token（不含 reasoning） | | tokens.reasoning | 思考 token（是总输出 token 的子集） |

满足恒等式（opencode packages/llm/src/schema/events.ts）：

input + cache.read + cache.write == 供应商上报的总输入 token
output + reasoning               == 供应商上报的总输出 token

因此本插件直接按上表相加，缓存与思考 token 各计一次，不会重复。

开发

npm install
npm run typecheck

主要文件：

• tui.tsx — 插件源码（TUI plugin，注册 sidebar_content slot），也是 npm 包入口
• .opencode/tui.json — 项目级 TUI 插件注册（开发模式）
• .opencode/package.json — 本地运行期依赖（opencode 启动时自动安装）
• package.json / tsconfig.json — npm 发布元数据 + 本地类型检查

贡献

欢迎提交 issue 和 PR。开发流程：

1. Fork 本仓库并 clone
2. npm install 后改 tui.tsx，用 npm run typecheck 验证类型
3. 本地启动 opencode（Ctrl+X B 打开侧边栏）验证效果
4. 提交 PR 并说明改动

License

MIT © omsfuk