# cursor-usage-alert

**Repository Path**: zhourui815/cursor-usage-alert

## Basic Information

- **Project Name**: cursor-usage-alert
- **Description**: 在 Cursor Agent / Ask 正常结束（stop hook、status: completed）时，读取本机登录态，调用 Cursor 账单只读接口，在屏幕右下角弹出置顶用量窗口
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cursor Usage

在 Cursor **Agent / Ask 正常结束**（`stop` hook、`status: completed`）时，读取本机登录态，调用 Cursor 账单只读接口，在屏幕右下角弹出**置顶用量窗口**（不依赖易被压掉的 Windows Toast）。

**开源地址**

| 平台 | 仓库 |
|------|------|
| GitHub | https://github.com/yuanzhang788/cursor-usage-alert |
| Gitee | https://gitee.com/zhourui815/cursor-usage-alert |

![用量弹窗示例（本机实机查账）](img/popup-usage.png)

*图：托盘「立即查用量」或 Agent 结束后的弹窗——第一行周期 Auto/API，第二行套餐内 token，第三行合计（万）。*

## 功能

- **第一行**：当前周期 `Auto` / `API` 占用百分比；仅在团队池或个人的 **已用 > 上限** 时显示「超出 $x.xx」（不是把团队池总花费直接当超出）。
- **第二行**：本次对话新入账事件的套餐内 `in / out / cache`。
- **第三行**：**合计 x.xx万**（in + out + cache，以万为单位，保留两位小数）。
- 账单晚于 hook 时，最多轮询约 **45 秒**（间隔 3 秒）；仍无 API 事件时，用 hook 传入的 token 显示兜底文案。
- 托盘常驻、单实例；**安装版首次启动**会自动写入用户级 `~/.cursor/hooks.json`。

## 目录结构

| 路径 | 说明 |
|------|------|
| `electron/` | 源码：托盘、`usage.js`（查账）、`hook.ps1` / `hook.js`（stop hook）、弹窗 UI |
| `release/` | `npm run dist` 默认输出（`win-unpacked` + NSIS 安装包） |
| `%LOCALAPPDATA%\Programs\Cursor Usage\` | 默认 NSIS 安装位置（含 `resources\hook.ps1`） |
| `%LOCALAPPDATA%\cursor-usage\` | 运行时：`inbox/`、`state.json`、`hook.log`、`tray.pid` |

## 环境要求

| 场景 | 要求 |
|------|------|
| **使用安装包 / 便携 exe** | Windows 10/11、已登录 Cursor、系统自带 PowerShell（**无需 Node**） |
| **开发 / 打包** | Node.js 18+、`npm` |

Token 来源：`%APPDATA%\Cursor\User\globalStorage\state.vscdb` 中的 `cursorAuth/accessToken`。

## 安装与使用

### 1. 打包（维护者）

```powershell
cd electron
npm install
npm run dist
```

产物：

- 便携：`release\win-unpacked\Cursor Usage.exe`
- 安装包：`release\Cursor Usage Setup 1.0.0.exe`

打包前 **先退出** 所有 `Cursor Usage.exe`，并避免 Cursor IDE 占用 `release\win-unpacked\resources\app.asar`（可先关 asar 标签或重启 Cursor）。仍失败时可改用其它输出目录：

```powershell
npx electron-builder --win nsis --config.directories.output=../release-build
```

### 2. 安装 / 运行（使用者）

1. 运行 Setup 或 `win-unpacked\Cursor Usage.exe`，确认任务栏托盘出现 **Cursor Usage** 图标。
2. **重启 Cursor**（或重载 hooks），使 stop hook 生效。
3. 正常结束一轮 Agent / Ask，右下角应弹出用量窗口（效果见文首截图）。

**不跑 Agent 时**：托盘右键 **「立即查用量」**，会马上请求一次 API 并弹窗（周期用量 + 水位之后的新入账事件，不更新水位）。

托盘启动时会向 `~/.cursor/hooks.json` 写入 **stop** 配置（并移除本工具旧的 hook 项）：

| 环境 | hook 命令 |
|------|-----------|
| **已安装 exe** | `powershell -NoProfile -ExecutionPolicy Bypass -File "<安装目录>\resources\hook.ps1"` |
| **源码开发** | `node "<项目>\electron\hook.js"` |

`timeout` 为 **60** 秒（与查账等待匹配）。

### 3. 为何不用 `Cursor Usage.exe --hook`

安装版是 **GUI 程序**，在 Windows 上通常 **读不到** Cursor 传入的 stdin，会出现 `hook.log` 里 `skipped … bytes=0`、不弹窗。  
因此安装版必须用 **`resources\hook.ps1`**（PowerShell 控制台读 stdin）；`hook.js` 仅用于开发机（需 Node）。

手动示例（安装后路径按本机调整）：

```json
{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<你>\\AppData\\Local\\Programs\\Cursor Usage\\resources\\hook.ps1\"",
        "timeout": 60
      }
    ]
  }
}
```

升级安装包后，若未重装，至少将新版 `electron\hook.ps1` 复制到安装目录的 `resources\`，并重启 Cursor。

### 4. 卸载

**不要用 Geek Uninstaller 强卸。** 桌面出现 `geek64.exe_….dmp` 表示 **Geek 自己崩溃**，与 NSIS 卸载脚本是否杀进程无直接关系；Geek 半删后常见「目录空、没有 Uninstall.exe、设置里已无条目」。

推荐顺序：

1. 托盘右键 **退出**（或任务管理器结束所有 `Cursor Usage.exe`）。
2. **设置 → 应用 → Cursor Usage → 卸载**，或运行  
   `%LOCALAPPDATA%\Programs\Cursor Usage\Uninstall Cursor Usage.exe`  
   （安装包内 NSIS 会在卸载前 `taskkill` 结束进程，见 `electron/build/installer.nsh`。）
3. 若已被 Geek 删乱，用项目自带脚本清理：

   ```powershell
   powershell -NoProfile -ExecutionPolicy Bypass -File electron\scripts\uninstall-cursor-usage.ps1 -RemoveHooks
   ```

   可选 `-RemoveAppData` 删除 `%LOCALAPPDATA%\cursor-usage\`（日志、水位、inbox）。

## 开发

```powershell
cd electron
npm install
npm start
```

- 托盘右键 **「立即查用量」**：单次查 API 并弹窗（与 Agent 结束后的展示一致，但不轮询 45 秒）。
- 生成弹窗截图（维护 README 用）：

  ```powershell
  .\node_modules\electron\dist\electron.exe . --refresh --screenshot=..\img\popup-usage.png
  ```

- 测 hook（PowerShell，与安装版一致）：

  ```powershell
  '{"conversation_id":"<UUID>","generation_id":"test","status":"completed","input_tokens":1}' |
    powershell -NoProfile -ExecutionPolicy Bypass -File .\hook.ps1
  ```

  检查 `%LOCALAPPDATA%\cursor-usage\hook.log` 是否出现 `enqueued …`。

- 测完整查账轮询：往 `%LOCALAPPDATA%\cursor-usage\inbox\` 写入：

  ```json
  {
    "conversation_id": "<当前对话 UUID>",
    "generation_id": "manual-test",
    "status": "completed"
  }
  ```

## 工作流程

```text
Cursor stop (completed)
  → hook.ps1（安装）或 hook.js（开发）
  → 解析 stdin，写入 inbox/*.json，必要时启动托盘
  → 托盘轮询 inbox → usage.js
  → GetCurrentPeriodUsage + GetFilteredUsageEvents
  → 弹窗 → 更新 state.json 水位 (lastTimestamp)
```

只读接口：`GetCurrentPeriodUsage`、`GetFilteredUsageEvents`（`page=1`，`pageSize=20`）。

## 排查

| 现象 | 建议 |
|------|------|
| 完全不弹窗 | 托盘是否在跑；`hook.log` 是否 `enqueued`（非 `bytes=0`） |
| `npm run dist` 失败 asar 占用 | 结束 Cursor Usage；关 Cursor 里对 `app.asar` 的占用；或输出到 `release-build` |
| `hook.log` 为 `skipped … bytes=0` | hooks 是否仍指向 `exe --hook`；改回 `hook.ps1` |
| 只有 Auto/API，「尚未入账」 | 账单延迟、conversation 未匹配或水位已超前；可试「立即查用量」看周期是否正常 |
| 改了源码 exe 不变 | 重新 `npm run dist` 并运行新 exe / 重装 |
| 请重新登录 Cursor | token 无效或缺失 |
| Geek 卸载崩溃 / 删不干净 | 勿用 Geek；用「设置 → 应用」或 `scripts/uninstall-cursor-usage.ps1` |

日志：`%LOCALAPPDATA%\cursor-usage\hook.log`（hook 入队 / 跳过）。

## 许可

本地自用工具；与 Cursor 官方无隶属关系。分享安装包时勿附带他人日志或账号信息。