JingbiaoMei/Tokdash
JingbiaoMei/Tokdash has 92 GitHub stars and 22 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 21:20 UTC. Last push 2026-11-10.
可以做什么
- Exact token counts: Input/Output/Cache token breakdowns
- Session explorer: per-session drill-down
- Contribution calendar: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
- Report tab: a week / month / year-to-date report of your own agent activity, with a shareable card for each tier of detail. Every export writes a light and a dark PNG
实测星标增长
- 24小时
- 0
- 7天
- 更新延迟
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Agent Dashboard: Visualization and analytics for Sessions and Quota Usage. Track, analyze, and optimize token usage across providers with heatmaps, cost tracking, token counting and quota resets..
开发工具README_CN.md
原文English | 中文 | 日本語 | 한국어 | Español | Português
适用于 AI 编程工具的本地 Token 与费用仪表盘
无需安装即可体验 → tokdash.github.io/demo
[!NOTE] 多台机器,一个仪表盘。 在设置里添加运行在 WSL、Mac 或其他机器上的 Tokdash 实例:每个视图都会合并你选择的范围,Servers 标签页并排对比各台机器,额度标签页则按机器分别展示各服务商的额度窗口进度条与重置倒计时。远程访问 → · 额度跟踪 →
同一作者的另一个项目:Cosyncing。 同步并操控你的 agent —— 从 CLI 到 GUI,从桌面到手机。Cosyncing 让你的编码 agent 在你自己的网络中保持同步。
目录
快速开始
pipx install tokdash
tokdash setup
就这两条命令。tokdash setup 会检测运行时、在需要时安装托管运行时、注册本地
服务,并打印仪表盘地址 —— http://127.0.0.1:55423。完整安装选项、首次运行
说明与更新方式见 安装与运行;想先逛逛?在线演示
运行在真实界面上。
一个包,四种视图
一个本地包,一个本地数据索引 —— 四种读取方式。每个界面解析的都是你自己机器上的同一批会话日志,因此浏览器仪表盘、终端、菜单栏,以及你 Agent 的状态栏永远口径一致。
| 视图 | 它是什么 | 什么时候用它 |
|---|---|---|
| WebUI | 完整仪表盘:Overview、Sessions、Stats、Report、Quota、Servers | 你想要全局视图、图表与逐层下钻 |
| TUI | tokdash tui —— 终端里的七个面板:Overview、Sessions、Stats、Report、Speed、Quota、Pricing |
你常驻终端,不想为了看数字打开浏览器 |
| Companion | 原生菜单栏(macOS)/ 通知区域(Windows)应用 | 你想全天可见今日费用与额度,哪怕仪表盘没有打开 |
| 状态栏 | 你 Agent 状态栏里的实时 Token / 费用条目 | 你想在打字的正下方看到费用跳动 |
WebUI
仪表盘是由本地 FastAPI 应用提供的单页应用:精确的输入 / 缓存 / 输出 Token 明细、按工具与按模型的表格、贡献热力图、周 / 月 / 年的 Report 报告、按服务商的 Quota 额度窗口与重置倒计时,以及可以合并、对比多台机器的 Servers 标签页。点击任意截图即可打开在线 Demo。
Overview
|
用量报告
|
额度追踪
|
多台服务器,一个总计
|
浅色与深色模式跟随系统外观。应用内置 17 款样式主题、明暗模式、PWA 安装与六种界面语言(English / 中文 / 日本語 / 한국어 / Español / Português)。
终端仪表盘(TUI)
更喜欢留在终端里?tokdash tui 无需浏览器就能打开七个面板 —— Overview、Sessions、Stats、Report、Speed、Quota 和 Pricing,读取同一个本地索引(当旁边运行着 tokdash serve 时,还会读取共享的磁盘数据库)。F1–F7 在它们之间跳转,v 列出全部面板。
TUI — Overview
|
TUI — Quota
|
tokdash tui
按键
| 按键 | 操作 |
|---|---|
q |
退出 |
r |
重新加载当前面板 |
F1–F7 |
Overview / Sessions / Stats / Report / Speed / Quota / Pricing(1 / 2 / 3 仍然跳到 Overview / Report / Quota) |
v |
从列表里选一个面板 |
t d w m y a |
设置共用的时间区间:今天、昨天、本周、本月、今年、全部 |
p |
更多区间(区间栏里的 More);在 Stats 里是更早的一年 |
P |
Stats:更晚的一年,一路回到最近 365 天 |
c |
手工输入精确的自定义日期区间 |
[ / ] |
按整个周期向前 / 向后平移 —— 绝不跳入未来 |
0 |
回到今天 |
/ |
在当前表格里搜索 |
s |
切换当前表格的排序 |
enter / esc |
打开选中的行 / 关闭它 |
h |
选择数据来源(Sessions 与 Speed) |
H |
在 Speed 的来源之间逐个切换 |
k |
选择 Speed 的曲线 |
x |
切换计时窗口(Speed) |
b |
切换 Speed 的分桶粒度 |
u |
轮询额度(仅 Quota 面板) |
? |
显示所有按键的帮助面板 |
一次性报表 CLI
用于可管道化或脚本化的一次性报表:
tokdash report --period week
周期是一个参数(flag),不是位置参数。可接受的值:today(默认)、week、month、year、all、天数数字,或 Nd/Nw/Nm/Ny 简写;其中 week、month 和 year 与 Web Report 标签页显示的日历对齐窗口相同。tokdash report 还支持 --json、--pretty 和 --output <file>,遵循与 tokdash export 相同的约定。
Companion 状态栏应用
可选的原生应用:macOS 菜单栏应用与 Windows 通知区域应用 —— 在不打开仪表盘的情况下,提供紧凑、只读的 Tokdash 服务视图。
|
|
| macOS 菜单栏 | Windows 通知区域 |
Windows —— Microsoft Store(推荐,由 Microsoft 签名,需要 Windows 11):
直接下载 —— 最新 Companion Release:
通用 DMG(arm64 + x86_64,macOS 14+)与自包含便携 ZIP(x64,Windows 11;Windows on Arm 可通过 x64 模拟运行)。
它显示什么,以及如何设置
- 今日费用、Token、消息数与本月累计用量
- 汇总多个 Tokdash 端点的总计,并按服务器分组显示额度
- Codex、Claude、Kimi、MiniMax、Antigravity、Grok 与 Z.ai 额度窗口
- 相对重置时间与可选的低额度通知
- 跟随系统语言,并支持 English、简体中文、日语、韩语、西班牙语与葡萄牙语
- 无遥测、凭据发现、端口扫描或直接日志解析
设置:运行 Tokdash 1.5.2 或更高版本(安装与运行),安装 Companion,
它默认连接 http://127.0.0.1:55423 —— 其设置允许你添加、测试、命名或移除明确
指定的端点,包括私有 Tailscale Serve 地址。Companion 只会访问你配置的端点;
低额度通知与登录时启动均为可选功能。
[!WARNING] GitHub Releases 提供的二进制文件未签名。macOS Gatekeeper 和 Windows SmartScreen 会显示未知发布者警告。请只从本仓库下载,使用随 Release 提供的
SHA256SUMS验证文件,并仅在你信任该 Release 时继续。 Microsoft Store 版本由 Microsoft 签名,不受此影响;macOS 的签名与公证 在后续版本中加入。
校验、更新与移除说明见 Companion Release 指南。
状态栏(Statusline)
本地 API 可以驱动编程 Agent 状态栏中的一个条目,实时显示 Token / 费用统计:
现成模板(bash 与 PowerShell)、安装 / 配置与端点参考见
docs/guides/statusline/。
安装与运行
平台支持
- Linux(含 WSL2): 支持
- macOS: 支持
- Windows(原生): 实验性支持
前置要求: Python 3.10+ 以及一个或多个 支持的客户端。
安装
推荐的隔离安装:
pipx install tokdash
如果你不使用 pipx:
python3 -m pip install --user tokdash
首次运行
运行 onboarding 向导:
tokdash setup
在平台支持时,向导会配置一个可逆的用户级后台服务,并打印仪表盘地址(默认
http://127.0.0.1:55423)。如果没有可用的服务管理器,它会记录 setup 状态并打印前台运行指引。
它默认只监听 localhost,本地服务不需要 sudo,并且除非你后续使用 --purge 卸载,否则会保留使用历史。
如果你通过 Agent、脚本或上层 bundle 做非交互安装,请运行
tokdash setup --auto --json;如需先预览 setup 会做什么,运行 tokdash setup --dry-run。
如需显式监听所有网络接口并保持写入接口禁用,请运行 tokdash setup --bind 0.0.0.0;
操作前请先阅读远程访问指南。
然后检查安装:
tokdash doctor
doctor 会检查运行时、后台服务、配置端口、数据路径以及更新检查状态。自动化场景可使用
tokdash doctor --json。
更新或移除
tokdash update # 升级受管运行时,并在可能时重启服务
tokdash uninstall # 精确撤销 setup 创建的内容;默认保留使用历史
update 只会驱动 Tokdash 能安全管理的安装方式。如果当前运行时来自 Tokdash 不拥有的包管理器,
它会打印明确的手动升级建议,而不是修改该环境。
既有安装:从 v1.0 之前迁移
如果你是在 onboarding 流程加入前安装的 Tokdash,请先升级:
pipx upgrade tokdash
# 或:python3 -m pip install --user -U tokdash
然后运行 tokdash doctor;当你希望 Tokdash 接管后台服务时,再运行 tokdash setup。如果你已经有
手写的 systemd 或 launchd 服务,setup 不会静默替换它:默认会拒绝覆盖未带 Tokdash setup 标记的
tokdash.service / plist。你可以继续自行维护该服务、先移除它再运行 setup,或在确认
tokdash setup --dry-run 输出后使用 tokdash setup --force。--force 也会处理已经占用
55423、但还没有新版 /health 指纹的 1.0 之前服务:它会重写并重启现有 tokdash.service。
如果要跳过服务创建,使用 tokdash setup --no-service。
如果当前 setup 使用的是 conda / 系统 Python / user-pip 解释器,而你希望后续由
tokdash update 自动管理升级,可以把服务迁移到 Tokdash setup 自己创建并拥有的 venv:
# 先升级你接下来要运行的 tokdash 命令,例如:
python3 -m pip install --user -U tokdash
# 如果是 conda base 安装:
conda run -n base python -m pip install -U tokdash
tokdash setup --runtime venv --force
tokdash doctor
这会保留 ~/.tokdash 下的使用历史,重写用户级服务,让它改为运行
~/.tokdash/runtime/python-venv/bin/python -m tokdash;之后 tokdash update 就可以升级这个
受管 venv 并重启服务。如果你使用的是 pipx 安装,也可以继续使用 pipx 运行时,并通过
tokdash update 或 pipx upgrade tokdash 升级。
前台运行备用方式
如果你只需要一次性的前台进程:
tokdash serve
打开 http://127.0.0.1:55423。如果默认端口被占用,使用 tokdash serve --port <port>。
默认情况下,tokdash serve 会在启动时在浏览器中打开仪表盘一次;传入 --no-open 可禁用。
不带子命令直接运行 tokdash 只会打印命令帮助然后退出 —— 它不会再在你背后悄悄启动
tokdash serve。
完整 onboarding 说明 —— 运行时选择、WSL/systemd 行为、macOS launchd、Tailscale、bundle
集成、更新检查与安全卸载语义 —— 见 docs/guides/ONBOARDING.md。
通过 Tailscale Serve、SSH 转发或显式网络绑定进行远程访问,见
docs/guides/REMOTE_ACCESS.md。
功能特性
- 精确 Token 统计:输入 / 输出 / 缓存 Token 明细
- 会话浏览器:逐会话下钻
- 贡献日历:2D 热力图 + 3D 等距视图,支持 Tokens / Cost / Messages 指标
- Report 标签页:本机 Agent 活动的周 / 月 / 年初至今报告,每个详细层级都配有可分享卡片;每次导出都会同时生成浅色与深色两张 PNG
- Quota 标签页:九家服务商的订阅窗口进度条与重置倒计时。Codex 窗口读取本地日志即可开箱使用;多数其他来源需要选择启用实时轮询
- 终端仪表盘 [新]:
tokdash tui—— 在终端里查看 Overview、Sessions、Stats、Report、Speed、Quota 和 Pricing,无需浏览器 - Companion 状态栏应用:在 macOS 菜单栏或 Windows 通知区域查看费用与订阅额度 —— Windows 版已上架 Microsoft Store
- 状态栏集成:在 Claude Code 的状态栏(或任何能访问本地 HTTP 端点的 Agent)中显示实时 Token 使用量
- 多服务器视图:在设置中添加 WSL、macOS 或其他 Tokdash 服务器;可合并任意选择的用量,并按机器分组显示额度。参见远程访问。
- 主题与应用体验:17 款样式主题、明暗模式、PWA 安装支持、六种界面语言
已支持客户端
Tokdash 读取 27 个已支持 Agent 的本机会话日志 —— 上方的品牌图标行列出了 它们的名字;完整矩阵(用量与费用 / 会话浏览器覆盖、各客户端数据路径、覆盖变量 与各来源的计费说明)见 已支持客户端。
额度跟踪(可选)
「额度」标签页展示九家服务商的订阅用量窗口与重置倒计时。Codex 的 5 小时 / 每周窗口读取本地日志即可开箱使用(请将其视为估算值);准确的 Codex 消耗与其余 全部服务商 —— Claude Code、Antigravity、MiniMax、Kimi Code、Grok、Z.ai、OpenCode Go、Command Code —— 来自选择启用的实时轮询:Tokdash 使用你的 CLI 已经登录的 身份调用各服务商自己的额度接口。默认关闭、按服务商授权、结果保存在本地数据库。
授权命令、总开关、轮询频率与按服务商的凭据说明见
docs/reference/QUOTA.md。
费用精度说明
Token 统计取决于各客户端本地记录的内容。费用默认由内置定价数据库(src/tokdash/pricing_db.json)计算;如果存在你在仪表盘定价设置中保存的覆盖文件 <data_dir>/pricing_db.json,则改用该覆盖文件。两种方式都可能滞后于真实服务商价格 —— 请将其作为估算值,如金额敏感请以你的账单来源为准。
历史数据保留
[!IMPORTANT] 保留你的历史。 Claude Code 与 Gemini CLI 默认会删除超过约 30 天的本地会话,因此 Tokdash 早期月份的统计可能会悄悄变少。
Tokdash 读取各客户端的本地会话日志;本地 SQLite 索引无法恢复在索引前 就被删除的日志。只有两个受支持的客户端会默认删除旧会话,且都只需改一行配置:
- Claude Code:把
{ "cleanupPeriodDays": 3650 }添加到~/.claude/settings.json(以及任何其他CLAUDE_CONFIG_DIR)。 - Gemini CLI:在
~/.gemini/settings.json中设置{ "general": { "sessionRetention": { "enabled": false } } }(工作区设置会覆盖用户设置)。
其他所有受支持的客户端默认都会无限期保留历史。完整的逐客户端清单、配置细节, 以及本地 SQLite 索引能保留什么、不能保留什么,详见 docs/reference/HISTORY_RETENTION.md。
路线图
参见 docs/development/ROADMAP.md。
贡献 / 安全
- 贡献指南:
docs/CONTRIBUTING.md - 安全策略:
docs/SECURITY.md
文档
完整文档位于 docs/(建议从索引开始),按分组组织:
- guides/ —— 面向任务的配置:onboarding、远程访问、状态栏、后台服务。
- reference/ —— 查阅资料:API 参考、配置、额度内部机制、支持的客户端、历史数据保留。
- development/ —— 更新日志、发布流程、路线图,以及公开的
technical-notes/技术笔记。
License
MIT License,详见 LICENSE。
