Skip to content

feat(cursor): optional per-device usage via Agent hooks - #699

Draft
HaofeiMa wants to merge 4 commits into
Javis603:mainfrom
HaofeiMa:feat/cursor-device-usage
Draft

HaofeiMa wants to merge 4 commits into
Javis603:mainfrom
HaofeiMa:feat/cursor-device-usage

Conversation

@HaofeiMa

@HaofeiMa HaofeiMa commented Sep 15, 2026

Copy link
Copy Markdown

Summary

Test plan

  • npm run verify
  • 打开「仅统计本机 Cursor 用量」后,本机 Agent 对话会写入 jsonl,且不再跑 cursor sync
  • 关掉开关后恢复账号级 CSV,且只移除我们自己的 hook
  • 未打开开关时行为和现在一致

Summary by cubic

Adds an opt-in per-device Cursor usage mode that records Agent stop hooks into a machine-local jsonl, so a Hub no longer sums the same account CSV on every device. Default remains account-level CSV.

Summary

  • New cursorUsageSource setting (account default | device), exposed as the Settings → Cursor "Count Cursor usage on this device only" checkbox and the TOKEN_MONITOR_CURSOR_USAGE_SOURCE env var.
  • Device mode installs a Cursor Agent stop/subagentStop hook into ~/.cursor/hooks/ and appends token counts to <sharedDataDir>/cursor-device/usage.jsonl, overridable via TOKEN_MONITOR_CURSOR_DEVICE_LOG.
  • Hook command paths are quoted with forward slashes so Windows installs do not break on escaping.
  • Device mode skips tokscale cursor sync and treats Cursor as a runtime-local adapter, so account totals are not double-counted; limits stay account-scoped.
  • The device jsonl directory is watched while the tokscale cache is not, so the self-trigger loop (issue macOS:并发 tokscale 扫描可能拖垮 syspolicyd,导致 Gatekeeper 返回 Too many open files #15) does not return.
  • Inclusive input_tokens are split so cache read/write is not double-counted by tokenValue().
  • Switching back to account mode removes only our hook marker and preserves unrelated hook commands.
  • Cloud Agent usage is not recorded.
  • Branch kept current with upstream v0.60.0, including the Cursor legacy-session fix.
Area Before After
Usage source Account-level CSV via tokscale cursor sync Default unchanged; optional device mode reads the local Agent stop-hook jsonl
Per-device totals Every device reports the same account CSV, which the Hub sums Device mode reports only local Agent usage, so per-device totals are accurate
Sync/watch tokscale cursor cache is not watched Device-mode jsonl dir is watched; tokscale cursor sync is skipped
Settings UX No device-scope option Settings → Cursor "Count Cursor usage on this device only" checkbox

Tests and risks

  • New unit tests cover hook install/uninstall (including Windows path quoting), device usage parsing, and collector integration; npm run verify passes.
  • Device mode requires the Cursor config directory to exist; hook install fails open and only logs an error otherwise.
  • The hook script uses only Node built-ins so the copied file runs without the rest of the app.
  • Draft pending direction on issue 希望 Cursor 用量也能按设备显示(多设备 Hub 目前会把同一账号加总) #698.
中文版本

新增可選的按裝置 Cursor 用量模式,透過 Agent 的停止掛鉤(stop hook)將用量記錄到本機 jsonl,令 Hub 不再於每部裝置上累加同一份帳號 CSV。預設仍為帳號層級 CSV。

摘要

  • 新增 cursorUsageSource 設定(預設 account | device),可透過「設定 → Cursor」的「僅統計本機 Cursor 用量」選項或 TOKEN_MONITOR_CURSOR_USAGE_SOURCE 環境變數啟用。
  • 裝置模式會將 Cursor Agent 的 stopsubagentStop 掛鉤安裝至 ~/.cursor/hooks/,並將 Token 用量附加至 <sharedDataDir>/cursor-device/usage.jsonl(可用 TOKEN_MONITOR_CURSOR_DEVICE_LOG 覆寫)。
  • 掛鉤指令路徑以正斜線加引號,避免 Windows 安裝因跳脫字元而失效。
  • 裝置模式不再執行 tokscale cursor sync,並將 Cursor 視為執行期本機介面卡,避免與帳號總量重複計算;額度仍按帳號統計。
  • 裝置模式的 jsonl 目錄會被監視,而 tokscale 快取則不會,因此不會再次觸發自我同步迴圈(issue macOS:并发 tokscale 扫描可能拖垮 syspolicyd,导致 Gatekeeper 返回 Too many open files #15)。
  • 含快取的輸入 Token 會拆分,避免 tokenValue() 重複計算快取讀取/寫入。
  • 切回帳號模式時只會移除我們自己的掛鉤標記,並保留其他掛鉤指令。
  • 不記錄 Cloud Agent 用量。
  • 分支已與上游 v0.60.0 同步,包括 Cursor 舊 session 修正。
範疇 之前 之後
用量來源 透過 tokscale cursor sync 取得帳號層級 CSV 預設不變;可選的裝置模式改為讀取本機 Agent 停止掛鉤的 jsonl
按裝置總量 每部裝置回報同一份帳號 CSV,由 Hub 累加 裝置模式只回報本機 Agent 用量,按裝置總量因此準確
同步/監視 tokscale cursor 快取不會被監視 裝置模式的 jsonl 目錄會被監視;不再執行 tokscale cursor sync
設定介面 沒有按裝置選項 「設定 → Cursor」新增「僅統計本機 Cursor 用量」選項

測試與風險

  • 新增單元測試涵蓋掛鉤安裝/移除(包括 Windows 路徑引號處理)、裝置用量解析及收集器整合;npm run verify 通過。
  • 裝置模式需要 Cursor 設定目錄存在;掛鉤安裝採取 fail-open,失敗時只記錄錯誤。
  • 掛鉤指令碼只使用 Node 內建模組,因此複製後可獨立執行,無需應用程式其餘部分。
  • 本 PR 為草案,等待 issue 希望 Cursor 用量也能按设备显示(多设备 Hub 目前会把同一账号加总) #698 的方向確認後才轉為 Ready。

Written for commit 840e3d3. Summary will update on new commits.

Review in cubic

Comment thread src/shared/providers/cursor/deviceHook.js Fixed
Co-authored-by: Cursor <cursoragent@cursor.com>

# Conflicts:
#	src/shared/collector.js
#	src/shared/hubBuildRegistry.json
#	worker/src/shared/hubBuildRegistry.json
Keep the opt-in Cursor per-device usage path while taking upstream through v0.60.0, including the Cursor legacy-session fix. The hub build registry records the combined clientHealth source list.

Co-authored-by: Cursor <cursoragent@cursor.com>
@coderabbitai

coderabbitai Bot commented Sep 22, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Comment @coderabbitai help to get the list of available commands.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants