# cursor_status **Repository Path**: sunkai64/cursor_status ## Basic Information - **Project Name**: cursor_status - **Description**: 获取windows端cursor执行状态,然后通过其他硬件设备播放、展示 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-06 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Cursor Status Monitor / Cursor 代理状态监视器 Windows background program that polls **Cursor Cloud Agents** execution status and embeds a LAN **Status Hub** for the desk puck (phase-1 PC-colocated design). Optional external `upload_status` POST remains available; no speaker/TTS on the Windows side yet (phase 2). Windows 后台程序:持续轮询 **Cursor Cloud Agents** 执行状态,并在**同一进程**内嵌局域网 Status Hub,供桌面灯/Puck 拉取 `/v1/display`(一期电脑兼顾方案)。外置 `upload_status` 仍可用;本程序暂不做扬声器/语音播报(二期)。 - 客户使用说明(对外):[`docs/监控器客户使用说明.md`](docs/监控器客户使用说明.md) - Hub 使用指导:[`docs/hub-guide.md`](docs/hub-guide.md) - 方案设计:[`docs/design/pc-colocated.md`](docs/design/pc-colocated.md) --- ## How it works / 工作原理 **Primary source (recommended):** Official [Cloud Agents API v1](https://cursor.com/docs/cloud-agent/api/endpoints) 1. `GET /v1/agents` — list recent agents (`id`, `name`, lifecycle `status`, `latestRunId`, `url`, timestamps) 2. `GET /v1/agents/{id}/runs/{runId}` — run execution status + terminal `result` summary **Auth:** Cursor Dashboard → API Keys. Set `CURSOR_API_KEY` (preferred) or `cursor.api_key` in config. API accepts Bearer or Basic. **Optional local hint:** Watches `%USERPROFILE%\.cursor\projects\*\agent-transcripts\` mtimes. Recent writes → `local_hints[]` with `status=running`. This is a coarse IDE-local signal only; it does **not** replace the Cloud API. **Status Hub (phase 1):** When `hub.enabled=true` (default in `config.example.yaml`), silent/tray mode starts an in-process HTTP server. Each poll writes the snapshot to memory. Puck firmware should `GET /v1/display`. **Upload hook:** `upload_status(payload)` POSTs the snapshot JSON when `upload.enabled=true`. Default off — not needed for the PC-colocated hub. --- ## Install (Windows) / 安装 Requirements: Python 3.10+ (`py` launcher recommended). From the project root (`cursor_status`): ```bat copy config.example.yaml config.yaml py -3 -m venv .venv .venv\Scripts\activate pip install -r requirements.txt ``` Set your API key (recommended via environment, not the YAML file): ```bat setx CURSOR_API_KEY "your_api_key_here" ``` Edit `config.yaml` for poll interval / hub port as needed. Ensure `hub.enabled: true` for phase-1 debugging. --- ## Phase-1 Hub debug / 一期调试 完整步骤见 **[`docs/hub-guide.md`](docs/hub-guide.md)**。摘要: After `scripts\run_silent.bat` (or tray), from the same PC or another LAN device: ```bat curl --noproxy "*" http://127.0.0.1:8787/health curl --noproxy "*" http://127.0.0.1:8787/v1/display curl --noproxy "*" http://127.0.0.1:8787/v1/status ``` (`--noproxy "*"` avoids corporate `HTTP_PROXY` hijacking localhost.) If `hub.token` (or `HUB_TOKEN`) is set: ```bat curl --noproxy "*" -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:8787/v1/display ``` Single-shot display without starting the LAN server: ```bat python -m cursor_status_monitor --mode once --print-display ``` **Firewall (Puck on Wi‑Fi):** allow inbound TCP 8787 and UDP 8788 (discovery) on the Private profile once (Admin PowerShell): ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\allow_hub_firewall.ps1 ``` The puck **auto-discovers** this PC via mDNS (`_cursor-status._tcp`) and UDP probe (`:8788`); a static `HUB_DISPLAY_URL` is optional. PC and puck must share the same Wi‑Fi (avoid guest / client-isolation SSIDs). | Method | Path | Purpose | | --- | --- | --- | | `GET` | `/health` | Liveness | | `GET` | `/v1/display` | Slim firmware contract (`mode` + `light`) | | `GET` | `/v1/status` | Full snapshot (debug) | | `POST` | `/v1/status` | Write snapshot (compat with upload hook) | --- ## Run as background / 后台运行 **Silent console loop:** ```bat scripts\run_silent.bat ``` or: ```bat python -m cursor_status_monitor --mode silent ``` **System tray:** ```bat scripts\run_tray.bat ``` **Single poll (debug):** ```bat python -m cursor_status_monitor --mode once --print-json ``` **Start with Windows login** (no console window; run `scripts\run_silent.bat` once first so `.venv` exists): ```powershell powershell -ExecutionPolicy Bypass -File .\scripts\install_startup.ps1 ``` The shortcut starts `pythonw.exe -m cursor_status_monitor --mode silent`. Output goes to `logs\monitor.log`. --- ## Configure hub / 配置本机 Hub In `config.yaml`: ```yaml hub: enabled: true bind: "0.0.0.0" port: 8787 token: "" # or env HUB_TOKEN / STATUS_UPLOAD_TOKEN discovery: enabled: true # mDNS + UDP so the light finds a moving LAN IP udp_port: 8788 ``` Env overrides: `HUB_ENABLED`, `HUB_BIND`, `HUB_PORT`, `HUB_TOKEN`, `HUB_DISCOVERY`, `HUB_DISCOVERY_UDP_PORT`. ## Configure external upload (optional) / 外置上传(可选) Only if you have a **separate** server (not the in-process hub): ```yaml upload: enabled: true url: "http://127.0.0.1:9999/v1/status" token: "" # or env STATUS_UPLOAD_TOKEN only_on_change: true ``` Or via env: ```bat set STATUS_UPLOAD_ENABLED=1 set STATUS_UPLOAD_URL=http://127.0.0.1:9999/v1/status set STATUS_UPLOAD_TOKEN=optional_bearer ``` Hook entrypoint: `cursor_status_monitor.upload.upload_status`. --- ## Status fields / 状态字段含义 | Field | Meaning / 含义 | | --- | --- | | `schema_version` | Payload schema (`1.0`) | | `generated_at` | Snapshot UTC time | | `monitor_host` | Windows hostname | | `agents[].id` | Cloud agent id (`bc-…`) | | `agents[].name` | Agent title / launch prompt | | `agents[].status` | Normalized: `running` / `idle` / `waiting` / `error` / `archived` / `unknown` | | `agents[].agent_status` | Raw API lifecycle: `ACTIVE` / `IDLE` / `ARCHIVED` | | `agents[].run_status` | Raw run: `CREATING` / `RUNNING` / `WAITING_FOR_BACKGROUND_WORK` / `FINISHED` / `ERROR` / … | | `agents[].run_id` | Latest run id | | `agents[].task_summary` | Run `result` text if finished; else agent name | | `agents[].url` | `https://cursor.com/agents/...` | | `agents[].created_at` / `updated_at` | API timestamps | | `agents[].polled_at` | When this monitor observed it | | `local_hints[]` | Optional IDE transcript activity (not cloud truth) | | `errors[]` | Cloud/local poll problems for this cycle. A failed upload is retried next poll and is not written into the payload it failed to send. | Normalized `status` mapping: - Agent `ACTIVE` or run `CREATING`/`RUNNING` → `running` - Run `WAITING_FOR_BACKGROUND_WORK` → `waiting` - Agent `IDLE` or run `FINISHED`/`CANCELLED`/`EXPIRED` → `idle` - Run `ERROR` → `error` - Agent `ARCHIVED` → `archived` --- ## Project layout / 目录 三块能力分开,前两块发给用户,OTA 不发: | 目录 | 给谁 | 做什么 | | --- | --- | --- | | `cursor_status_monitor/` | 用户电脑 | 轮询 Cursor,局域网只提供 `/v1/display` | | `cursor_status_display/` | 灯 | 拉灯光;仅当配置了 `OTA_BASE_URL` 才向运维服务查升级 | | `ota/` | 运维,不随上面两份发出 | 升级指令和页面,`python3 server.py`,默认 `:8788` | ``` cursor-status-monitor/ README.md config.example.yaml requirements.txt docs/design/pc-colocated.md cursor_status_monitor/ # 用户:Windows 监视器 + 灯光 Hub cursor_status_display/ # 用户:灯固件 ota/ # 运维:OTA 服务,不进用户包 scripts/ run_silent.bat run_tray.bat install_startup.ps1 allow_hub_firewall.ps1 ``` **Entrypoint:** `cursor_status_monitor/__main__.py` → `python -m cursor_status_monitor` --- ## Limitations / 限制 1. **Cloud agents only via official API.** Local Cursor IDE Composer/Agent chats are not fully exposed by a public API. Local transcript watching is a weak activity hint only. 2. **API key required** for useful cloud status. Without it, the monitor still runs and can emit local hints + empty `agents`. 3. **Task summary while running** is limited: mid-run streaming text is available via the SSE stream endpoint, but this monitor uses poll + Get Run (result text appears mainly when a run finishes). While running, `task_summary` falls back to the agent `name`. 4. **Does not reverse-engineer** Cursor binaries or private `state.vscdb` schemas (those change often and are undocumented). 5. **Rate limits:** keep `poll_interval_seconds` ≥ 15–30. Run details are fetched for `enrich_statuses` (default `ACTIVE` and `IDLE`). A finished run is cached, so steady-state polls only refetch agents that are still `ACTIVE`. The list call returns one page (`list_limit`, max 100). 6. **Windows-first.** Tray extras install only on Windows; silent mode can be smoke-tested elsewhere. --- ## Credentials checklist / 凭据清单 | Credential | Where | Required | | --- | --- | --- | | `CURSOR_API_KEY` | Cursor Dashboard → API Keys | Yes (for cloud status) | | `HUB_TOKEN` / `hub.token` | LAN puck auth (optional) | Optional | | `STATUS_UPLOAD_TOKEN` | External upload / shared with hub | Optional | | `upload.url` | External status server only | When `upload.enabled` | Official docs: https://cursor.com/docs/cloud-agent/api/endpoints · https://cursor.com/docs/api