在 Paseo 中查看各编码 Agent 的本地用量统计。

数据源（在 daemon 所在机器本地读取；远端机器数据经 SSH 采集，见下文）：

• Claude Code：~/.claude/projects（含 subagents）
• Codex：~/.codex/sessions 与 ~/.codex/archived_sessions
• OpenCode：~/.local/share/opencode/opencode.db（通过 node:sqlite 只读；reasoning token 计入输出，与计费口径一致）
• Pi：~/.pi/agent/sessions（含 forks 与子会话目录；跨文件按消息去重，fork 复制段不重复计）

界面：侧边栏底部「用量」行显示今日 token；点击打开全屏页，支持近24小时 / 今日 / 近 7 天 / 近 30 天 / 近 12 周 / 近 12 月 / 自定义日期范围（日历圈选起止），趋势图可在小时 / 日 / 周 / 月 四种聚合粒度间切换（默认日，范围与粒度相互独立）。

• 顶部两层页签：① 设备切换（聚合 / 本机 / 各远端，「聚合」在最前）② Agent 页签（总览 + 会话 + Claude Code / Codex / OpenCode / Pi）；「配置」入口在右上角刷新按钮右侧（含 Agent 统计开关与 SSH 主机管理）
• 总览：总量卡片、趋势图（可切换柱状图 / 折线图，聚合粒度四段开关）、按 Agent / 模型 / 项目 的明细；底部「统计口径与已知差异」说明与 CC Switch 等代理工具的对比口径（含无法对齐的原因）
• 图表交互：鼠标悬浮（或点按）图表查看当期用量明细（总 token 与各 Agent 拆分）；悬浮提示显示完整周期标签（如 2026-08-15 14:00）
• Agent 页签：该 Agent 的概况卡片、趋势图（与总览共用小时/日/周/月粒度开关）、模型明细、项目明细、会话明细与请求日志。会话明细按会话（session ID）聚合并按开始时间倒序：显示首条用户消息作为标题（部分注入文本会被跳过，无标题则显示会话 ID 前 8 位）、项目、请求数、token、输入/输出/缓存与时长，每页 20 条分页；会话数覆盖时间范围内该 Agent 的全部会话，列表展示最近 200 个，会话归属按其首次请求时间落入所选范围。请求日志（时间、模型、项目、会话、输入/输出/缓存 token）只保留每个 Agent 最近约 400 条调用，会话列表与请求日志均每页 20 条分页查看

刷新机制：首次扫描全量历史日志（本机约 30 秒，其间页面显示扫描进度），之后按文件增量刷新（约 1~2 秒）；Agent 回合结束后会自动触发防抖增量刷新。插件升级后（v0.3.0 起统计数据按小时与会话缓存）会有一次全量重扫。会话索引最多保留 8000 个最近会话（超出按会话末次活动时间淘汰）。

配置（用量页右上角「配置」或 Paseo 设置 → 插件）：

• 通用：界面语言（跟随系统 / 中文 / English，自动检测系统语言）与定时刷新（关闭 / 5 分钟 / 15 分钟 / 30 分钟（默认） / 1 小时 / 6 小时 / 24 小时；定时自动扫描本地日志并同步远端主机）；还可自定义本机标签（设备页签与请求日志里默认「本机」的显示名称，留空恢复默认，仅保存于本机偏好文件），以及默认时间范围与趋势粒度（打开用量页时的初始范围/粒度，如「当日 + 小时」「近 7 天 + 月」等，未设置时为近 7 天 + 日）
• Agent 开关：关闭的 Agent 不展示、不拉取
• 远端主机（SSH）：增删改与测试连接

远端统计（SSH）

可以把其他机器上的用量一起统计进来。两种配置方式：

1. 可视化配置（推荐）：用量页右上角「配置」入口，或 Paseo 设置 → 插件 → Agent Usage，在其中增删改 SSH 主机、测试连接；保存后新主机/变更主机会自动拉取
2. 手动编辑插件数据目录的 hosts.json（~/.paseo/plugin-data/agent-usage-plugin/hosts.json）：

[
  { "name": "dev1", "target": "dev1" },
  { "name": "srv2", "target": "user@10.0.0.2", "passwordCommand": "security find-generic-password -s agent-usage-ssh-srv2 -w" }
]

• target：~/.ssh/config 别名或 user@host；认证默认走 SSH 密钥，也支持账号密码：password 字段（明文，注意文件权限）或更安全的 passwordCommand（从钥匙串/密码管理器取密码）
• 可选字段：port、identityFile、nodePath（远端 node 路径）、cacheDir（远端增量缓存目录）、timeoutMs、enabled
• 远端要求：无需安装任何额外软件，插件自动探测 JS 运行时（PATH / nvm / volta / fnm / asdf / homebrew 等常见位置，并尝试加载 ~/.nvm/nvm.sh）；探测不到时才需要填 nodePath。SQLite 源需 Node ≥ 22.5，否则自动跳过；首次拉取为全量，之后增量
• 安全：插件不读取/解密任何远端凭据；远端只读日志，仅写一个小增量缓存（~/.cache/agent-usage-plugin）
• 界面：顶部「设备」页签可切换聚合 / 单机视图（页签下方显示各机器的同步状态）；请求日志带设备来源标签

数据与权限

• 读取：本机（及各远端主机）的本地会话日志
• 写入：daemon 所在机器的插件数据目录（扫描状态与主机配置）；远端仅写增量缓存
• 网络：插件自身的网络访问只有版本更新检查（每小时最多一次，仅读取公开的 registry 记录与对应提交的 package.json，来自 raw.githubusercontent.com、api.github.com，不发送任何数据）；SSH 采集通过系统 ssh 命令连接你配置的主机
• 不读取、不保存、不发送任何登录凭据；不发送 prompts、代码或日志内容到任何服务
• 支持 macOS 与 Linux；需要 Paseo 0.11.2 或更高版本

---

Agent Usage (English)

View local usage statistics for coding agents inside Paseo.

Data sources (read locally on the daemon host; remote machines are collected over SSH, see below):

• Claude Code: ~/.claude/projects (including subagents)
• Codex: ~/.codex/sessions and ~/.codex/archived_sessions
• OpenCode: ~/.local/share/opencode/opencode.db (read-only via node:sqlite; reasoning tokens count as output, matching the billing basis)
• Pi: ~/.pi/agent/sessions (including forks and sub-session directories; messages are deduplicated across files, so copied fork segments are not counted twice)

Interface: the "Usage" row at the bottom of the sidebar shows today's tokens; clicking it opens a full-screen page with ranges (last 24 hours / today / last 7 days / last 30 days / last 12 weeks / last 12 months / custom range picked on a calendar), and the trend chart switches between hour / day / week / month aggregation (day by default; range and granularity are independent).

• Two-level tabs at the top: (1) device switching (aggregate / local / each remote, with "aggregate" first) and (2) agent tabs (overview + sessions + Claude Code / Codex / OpenCode / Pi); the "Settings" entry sits to the right of the refresh button at the top right (agent toggles and SSH host management)
• Overview: total cards, trend chart (bar or line, four-segment granularity switch), breakdowns by agent / model / project; a "counting basis and known differences" note at the bottom explains the comparison with proxy tools such as CC Switch (including why some figures cannot be aligned)
• Chart interaction: hover (or tap) the chart to see that period's usage detail (total tokens split by agent); the tooltip shows the full period label (for example 2026-08-15 14:00)
• Agent tab: summary cards, trend chart (sharing the hour/day/week/month switch with the overview), model breakdown, project breakdown, session breakdown, and request log. Sessions are aggregated by session ID and sorted by start time: each row shows the first user message as the title (some injected text is skipped; otherwise the first 8 characters of the session ID), project, request count, tokens, input/output/cache split, and duration, 20 per page; the count covers every session of that agent in the range while the list shows the latest 200, and a session belongs to the range its first request falls into. The request log (time, model, project, session, input/output/cache tokens) keeps only the most recent ~400 calls per agent; both the session list and the request log paginate 20 rows per page

Refresh: the first scan reads the full history (about 30 seconds locally, with progress shown on the page), after which files refresh incrementally (about 1-2 seconds); a debounced incremental refresh triggers automatically when an agent turn ends. After a plugin upgrade (from v0.3.0, statistics are cached per hour and per session) one full rescan runs. The session index keeps at most the 8,000 most recent sessions (older ones are evicted by last activity time).

Settings (the "Settings" entry at the top right of the usage page, or Paseo Settings → Plugins):

• General: interface language (follow system / Chinese / English, auto-detected) and auto refresh (off / 5 min / 15 min / 30 min (default) / 1 hour / 6 hours / 24 hours; periodically scans local logs and syncs remote hosts); you can also set a custom local device label (the display name used instead of the default "本机 / Local" in the device tabs and request log; leave empty to restore the default, stored only in the local preference file), and a default range and trend granularity (the initial range/granularity when the usage page opens, such as "today + hour" or "last 7 days + month"; unset means last 7 days + day)
• Agent toggles: disabled agents are neither shown nor fetched
• Remote hosts (SSH): add, edit, delete, and test connections

Remote statistics (SSH)

Usage from other machines can be counted in as well. Two ways to configure it:

1. Visual configuration (recommended): the "Settings" entry at the top right of the usage page, or Paseo Settings → Plugins → Agent Usage, to add, edit, delete SSH hosts and test connections; new or changed hosts are fetched automatically after saving
2. Edit hosts.json in the plugin data directory manually (~/.paseo/plugin-data/agent-usage-plugin/hosts.json):

[
  { "name": "dev1", "target": "dev1" },
  { "name": "srv2", "target": "user@10.0.0.2", "passwordCommand": "security find-generic-password -s agent-usage-ssh-srv2 -w" }
]

• target: an alias from ~/.ssh/config or user@host; authentication uses SSH keys by default, and account passwords are also supported via the password field (plaintext, mind file permissions) or the safer passwordCommand (fetches the password from the keychain or a password manager)
• Optional fields: port, identityFile, nodePath (remote node path), cacheDir (remote incremental cache directory), timeoutMs, enabled
• Remote requirements: no extra software to install; the plugin auto-detects a JS runtime (common locations under PATH / nvm / volta / fnm / asdf / homebrew, and tries to load ~/.nvm/nvm.sh); fill nodePath only when detection fails. The SQLite source needs Node >= 22.5, otherwise it is skipped; the first fetch is full, later ones incremental
• Security: the plugin never reads or decrypts any remote credentials; remote logs are read-only and only a small incremental cache is written (~/.cache/agent-usage-plugin)
• Interface: the "Device" tabs at the top switch between aggregate and single-machine views (sync status per machine shows below the tabs); request log rows carry a device source label

Data and permissions

• Reads: local session logs on this machine (and on each remote host)
• Writes: the plugin data directory on the daemon host (scan state and host configuration); on remotes only the incremental cache
• Network: the plugin's own network access is only the update check (at most once an hour, reading only the public registry record and the pinned package.json from raw.githubusercontent.com and api.github.com, sending no data); SSH collection connects to your configured hosts through the system ssh command
• No login credentials are read, stored, or sent; no prompts, code, or log content is sent to any service
• Supports macOS and Linux; requires Paseo 0.11.2 or later