### Getting Started Walkthrough

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Details the onboarding flow provided by the `contributes.walkthroughs` entry, guiding new users through initial setup.

```APIDOC
## Getting Started Walkthrough

A `contributes.walkthroughs` entry provides a step-by-step onboarding flow:

1. **Enter License Key** — with command link and buy link (UTM-tagged)
2. **Verify CDP Connection** — instructions for `--remote-debugging-port=9222`, start server command
3. **Configure Networking** — open Setup Panel command
4. **Set Up Telegram** — optional, open Setup Panel command
5. **Done** — summary with link to documentation
```

--------------------------------

### Server Startup Output Example

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Example output shown after starting the server, indicating connection URLs and Telegram bot status.

```text
[main] CDP URL: http://127.0.0.1:9222
[main] Server: http://127.0.0.1:3000
[telegram] Bot connected (sync: off, users: 0)
[telegram] To register, send: /register A1B2C3D4
```

--------------------------------

### Install and Run Standalone Server

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Installs CursorRemote, clones the repository, sets up dependencies, and starts the development server. Requires Node.js 20+ and Cursor IDE with remote debugging enabled.

```bash
git clone https://github.com/len5ky/CursorRemote.git cursor-ide-remote
cd cursor-ide-remote
npm install
cp .env.example .env
npm run dev
```

--------------------------------

### Start Command

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

This command starts the server and automatically creates the temporary directory.

```bash
npm start
```

--------------------------------

### Build and Start Standalone Server in Production

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Builds the CursorRemote application for production and starts the server. Ensure the license key file exists before running in production mode.

```bash
npm run build
npm start
```

--------------------------------

### Install CursorRemote Extension

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Install the CursorRemote extension from a .vsix file using the command line. Ensure you have Cursor installed.

```bash
cursor --install-extension cursor-remote-0.1.46.vsix
```

--------------------------------

### Install Tailscale on Linux/WSL2

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Installs Tailscale on Linux or WSL2 systems using a curl script and then enables it. Follow the printed auth URL to log in.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
```

--------------------------------

### Install Tailscale on macOS

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Installs Tailscale on macOS using Homebrew and then enables it.

```bash
brew install tailscale
sudo tailscale up
```

--------------------------------

### Run Development Server

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Starts the development server with hot-reloading. Prompts for a license key if one is missing.

```bash
npm run dev
```

--------------------------------

### Install Cursor Remote

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Clone the repository, navigate to the directory, install dependencies, and copy the environment file.

```bash
git clone https://github.com/len5ky/CursorRemote.git cursor-ide-remote
cd cursor-ide-remote
npm install
cp .env.example .env
```

--------------------------------

### Setup Panel (WebviewPanel)

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

The interactive configuration wizard opened via `cursorRemote.openSetup`. It allows users to configure networking, password, and Telegram settings.

```APIDOC
## Setup Panel (WebviewPanel)

Interactive configuration wizard opened via `cursorRemote.openSetup`. Created in `ViewColumn.One` with `retainContextWhenHidden: true`.

### Networking Tab
- **Radio group**: Localhost / LAN / Specific address (Tailscale/custom)
- Custom address text input (shown when "Specific address" selected)
- **Save & Restart** button — updates settings and restarts server
- Tailscale documentation link

### Password Section
- Editable text input with current password
- **Copy** and **Save** buttons
- Server URL displayed for reference

### Telegram Tab
- **Step 1: Create Bot** — link to @BotFather, token input (or masked display if already set)
- **Step 2: Create Supergroup** — instructions for Topics and admin setup
- **Step 3: Register** — displays the actual `/register <token>` command from `telegram-auth.json`, copyable. Shows registered users and usernames.
- **Step 4: Sync** — instructions to send `/sync`

### Footer
- **Open All Settings** button — disposes the webview panel first, then opens VS Code Settings filtered to `@ext:cursor-remote.cursor-remote` on a deferred tick (avoids Cursor renderer freeze from retained webview + settings editor conflict)
```

--------------------------------

### Start Compiled Server

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Runs the compiled server application.

```bash
npm run start
```

--------------------------------

### Replay Output Log Example

Source: https://github.com/len5ky/cursorremote/blob/main/docs/cdp-record-replay.md

Example of the console output generated during a replay session.

```text
[replay] Loaded 47 snapshots from data/recording-2026-03-24T00-24-00.jsonl
[replay] Speed: 10x, thread: 12345, chat: -1001234567890

[replay] Bot: @cursor_controller_bot

[+0.1s] SEND  activity "Planning next moves" -> msgId=100
[+0.4s] SEND  human "fix the bug in config.ts" -> msgId=101
[+0.8s] EDIT  activity msgId=100 "Generating"
[+1.2s] DELETE activity msgId=100
[+1.3s] SEND  tool "Edit config.ts  +14 -7" -> msgId=102
[+1.5s] SEND  assistant "I've fixed the configuration issue..." -> msgId=103
[+2.0s] EDIT  tool msgId=102 "Edit config.ts  +14 -7"

[replay] Done -- 4 content messages, 47 snapshots replayed
```

--------------------------------

### Telegram Registration Command Example

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Example command to send in your Telegram group to register with the server. The token is provided in the server output.

```text
[telegram] To register, send in your Telegram group: /register A1B2C3D4
```

--------------------------------

### Run in Production (Compiled)

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Build and start the compiled production version of CursorRemote. Ensure the license key file exists.

```bash
npm run build
npm start
Ensure data/license.key exists before running npm start (no prompt in production mode).
```

--------------------------------

### Install Tailscale on Windows 11

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Installs Tailscale on Windows 11 using winget and then enables it. Alternatively, download from tailscale.com/download or use the App Store version.

```powershell
winget install tailscale
tailscale up
```

--------------------------------

### Run Command Display

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram_prd.md

Illustrates how to run commands outside a sandbox environment, specifying the command and its arguments. Includes an example of changing directory and executing a Node.js script.

```html
<b>🖥 Run outside sandbox:</b> cd, source, npx, python3

<pre>$ cd /home/user/project && npx convex run ...</pre>
```

--------------------------------

### Run in Production with tmux

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Use this command to start a new tmux session and run the development server for CursorRemote in a detached state.

```bash
tmux new -s cursor-remote
npm run dev
# Ctrl+B D to detach
```

--------------------------------

### Run DOM Discovery Tool

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Launches the DOM discovery tool.

```bash
npm run discover
```

--------------------------------

### Health Endpoint Response

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Example fields returned by the richer `/health` endpoint, designed for backward compatibility.

```json
{
  "windows": ...,
  "activeWindowId": ...,
  "mode": ...,
  "model": ...,
  "chatTabCount": ...,
  "pendingApprovalCount": ...,
  "generation": ...,
  "uptime": ...,
  "authRequired": ...
}
```

--------------------------------

### GET /health

Source: https://github.com/len5ky/cursorremote/blob/main/docs/architecture.md

Retrieves the current health status and state of the CursorRemote agent, including connection status, active windows, and current model configuration.

```APIDOC
## GET /health

### Description
Returns the current operational status of the agent, including uptime, connection status, and UI state metrics.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Status of the agent
- **connected** (boolean) - CDP connection status
- **agentStatus** (string) - Current status of the agent
- **clients** (number) - Number of connected clients
- **uptime** (number) - Uptime in milliseconds
- **windows** (array) - List of active windows
- **activeWindowId** (string) - ID of the active window
- **mode** (string) - Current composer mode
- **model** (string) - Current model name
- **chatTabCount** (number) - Number of open chat tabs
- **pendingApprovalCount** (number) - Number of pending approvals
- **generation** (boolean) - Current generation status

#### Response Example
{
  "ok": true,
  "connected": true,
  "agentStatus": "ready",
  "clients": 1,
  "uptime": 3600000,
  "windows": [],
  "activeWindowId": "win-1",
  "mode": "composer",
  "model": "claude-3.5-sonnet",
  "chatTabCount": 2,
  "pendingApprovalCount": 0,
  "generation": false
}
```

--------------------------------

### Build Project

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Compiles TypeScript code and copies client assets.

```bash
npm run build
```

--------------------------------

### Development and Build Commands

Source: https://github.com/len5ky/cursorremote/blob/main/CLAUDE.md

Common npm scripts for development, building, testing, and releasing the project. Use `npm run dev` for hot-reloading during development.

```bash
npm run dev          # Development with hot-reload (tsx watch)
npm run build        # TypeScript compile + copy client assets
npm run build:ext    # Bundle VS Code extension (esbuild)
npm run watch:ext    # Watch-mode for extension dev
npm start            # Run compiled server
npm test             # Run tests: npx tsx --test tests/*.test.ts
npm run package      # Bump patch + package .vsix into releases/
npm run release -- patch|minor|major  # Bump version, changelog, git tag
npm run discover     # DOM discovery tool against live Cursor
```

--------------------------------

### Browser Notification Event Types

Source: https://github.com/len5ky/cursorremote/blob/main/docs/architecture.md

Examples of message types that trigger browser notifications, including global approvals, run command prompts, and tool-level approvals.

```javascript
type: 'run_command'
```

```javascript
type: 'tool'
```

--------------------------------

### Build VS Code Extension

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Bundles the VS Code extension for distribution.

```bash
npm run build:ext
```

--------------------------------

### Configure Standalone Server Host and Password

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Sets both the server host to a specific Tailscale IP and configures a web application password for an additional layer of security. Both are set in the .env file.

```bash
# .env
SERVER_HOST=100.64.1.23
WEBAPP_PASSWORD=my-secret-password
```

--------------------------------

### POST /register

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram_prd.md

Registers a user with the bot using a token generated at server startup.

```APIDOC
## POST /register

### Description
Registers the current Telegram user with the bot using the authentication token provided in the server console.

### Method
POST

### Endpoint
/register <token>

### Parameters
#### Path Parameters
- **token** (string) - Required - The 32-character registration token generated on server startup.
```

--------------------------------

### Server Build Configuration

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

esbuild configuration for bundling the server's TypeScript entry point into an ESM module, including CJS compatibility shims.

```javascript
esbuild bundles `src/server/index.ts` + all Node.js dependencies → `dist/server/bundle.mjs`
Format: ESM, platform: Node
Banner injects CJS compatibility shims (`__dirname`, `__filename`, `createRequire`) for bundled packages (Express, etc.) that rely on these globals
No `node_modules` needed in the extension package
```

--------------------------------

### Build and Distribution

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Information regarding the build process for the extension, server, and client components.

```APIDOC
## Build and Distribution

### Extension Build
- esbuild bundles `extension/src/extension.ts` → `dist/extension.cjs`
- Format: CommonJS, platform: Node, external: `['vscode']`

### Server Build
- esbuild bundles `src/server/index.ts` + all Node.js dependencies → `dist/server/bundle.mjs`
- Format: ESM, platform: Node
- Banner injects CJS compatibility shims (`__dirname`, `__filename`, `createRequire`) for bundled packages (Express, etc.) that rely on these globals
- No `node_modules` needed in the extension package

### Client Build
- `tsc` compiles TypeScript
- `src/client/` copied to `dist/client/`
- `socket.io.min.js` copied from `node_modules` to `dist/client/`
```

--------------------------------

### Record and Replay Workflow for Debugging

Source: https://github.com/len5ky/cursorremote/blob/main/docs/cdp-record-replay.md

Use these commands to record an issue in Cursor and then replay it to debug. Ensure you have a Telegram group set up for checking the output.

```bash
# 1. Start recording while reproducing the issue
npm run record -- --window cursor-ide

# 2. Do the thing in Cursor that triggers the bug
#    (e.g. start an agent task, wait for activity indicators)

# 3. Stop recording (Ctrl+C)

# 4. Create a test topic in your Telegram group

# 5. Replay to see what the relay would send
npm run replay -- data/recording-2026-03-24T00-24-00.jsonl --thread 99999 --speed 5

# 6. Check the test topic in Telegram -- does it look right?

# 7. Fix the code, replay the same recording, compare
npm run replay -- data/recording-2026-03-24T00-24-00.jsonl --thread 99999 --speed 5
```

--------------------------------

### Configure Telegram Bot Token for Standalone

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Edit the .env file to enable Telegram integration and provide your bot token obtained from BotFather.

```bash
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### CursorRemote Project Structure

Source: https://github.com/len5ky/cursorremote/blob/main/CLAUDE.md

Overview of the project's directory structure and the purpose of key subdirectories and files. The extension and server are separate TypeScript projects.

```text
extension/          VS Code extension (separate TS project, esbuild bundle)
  └─ src/           Extension code — imports vscode only, never src/server/
                    Communicates with server via: env vars, HTTP /health, stdout parsing

src/server/         Node.js relay server (ESM, strict TypeScript)
  index.ts          Composition root — wires modules, no business logic
  cdp-client.ts     Lightweight CDP WebSocket client (NOT Puppeteer)
  cdp-bridge.ts     Discovers all Cursor window targets, holds CdpClient refs
  window-monitor.ts Polls all windows in parallel via separate CDP connections
  dom-extractor.ts  Runs inside Cursor's browser context via Runtime.evaluate
  state-manager.ts  EventEmitter — emits state:patch, connection:changed
  command-executor.ts  Handles commands from web/Telegram clients
  relay.ts          Express + socket.io server
  config.ts         Single source for all configuration (reads env vars)
  types.ts          Shared types — import from here, don't redeclare
  transports/
    telegram/
      Grammy-based bot with forum topic auto-creation

src/client/         Vanilla HTML/CSS/JS web client (no build step, served as static)
  app.js            Mobile-first UI, socket.io for real-time updates

src/discovery/      CDP DOM discovery/debugging tools
```

--------------------------------

### Configure Mirrored Networking for WSL2

Source: https://github.com/len5ky/cursorremote/blob/main/docs/setup-guide.md

Add this configuration to %UserProfile%\.wslconfig on Windows to enable mirrored networking for WSL2. Restart WSL2 afterwards.

```ini
[wsl2]
networkingMode=mirrored
```

--------------------------------

### Configure Raw Transport via Environment Variable

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram-troubleshooting.md

Set the transport engine to raw to bypass the Grammy framework.

```text
TELEGRAM_IMPL=raw
```

--------------------------------

### Record Cursor IDE Session

Source: https://github.com/len5ky/cursorremote/blob/main/docs/cdp-record-replay.md

Commands to initiate a recording session, with an optional flag to target a specific window.

```bash
npm run record                            # record first Cursor window
npm run record -- --window cursor-ide     # match window by title substring
```

--------------------------------

### Extension Build Configuration

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

esbuild configuration for bundling the extension's TypeScript entry point into a CommonJS module for Node.js.

```javascript
esbuild bundles `extension/src/extension.ts` → `dist/extension.cjs`
Format: CommonJS, platform: Node, external: `['vscode']`
```

--------------------------------

### Plan Widget Display

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram_prd.md

Shows a plan widget with a title, description, to-do list, and model information. To-dos are indicated with status icons: ✅ for completed, 🔵 for in progress, and ⚪ for pending.

```html
<b>📋 Telegram Integration Module</b>
<i>telegram_integration_module.plan.md</i>

Design and implement a Telegram bot transport...

<b>To-dos (3/10):</b>
✅ Write docs/telegram_prd.md
✅ Write docs/telegram_architecture.md
🔵 Add PlanWidget and RunCommand types
⚪ Update web client
⚪ Create Transport interface
<i>... 5 more</i>

Model: Opus 4.6
```

--------------------------------

### Client Build Configuration

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Build process for the client-side code, involving TypeScript compilation and copying static assets.

```javascript
`tsc` compiles TypeScript
`src/client/` copied to `dist/client/`
`socket.io.min.js` copied from `node_modules` to `dist/client/`
```

--------------------------------

### Identify Orphaned Processes on Linux/WSL

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram-troubleshooting.md

Locate running instances of the server to resolve 409 Conflict errors.

```bash
ps aux | grep cursor-remote
lsof -i :3000
```

--------------------------------

### Configure Standalone Server Host

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Sets the server to listen only on the specified Tailscale IP address by configuring the SERVER_HOST environment variable in a .env file. This restricts access to the Tailscale network.

```bash
# .env
SERVER_HOST=100.64.1.23   # your Tailscale IP
```

--------------------------------

### Open Dropdown and Select Item with JavaScript

Source: https://github.com/len5ky/cursorremote/blob/main/docs/architecture.md

Use JavaScript's `.click()` method to open dropdowns and select items. A short delay is recommended between opening and selecting to allow the menu to render.

```javascript
document.querySelector(trigger).click()
```

```javascript
document.querySelector(item).click()
```

--------------------------------

### License Flow

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Describes the process of reading, validating, and storing the license key, and how it's used by the extension and server.

```APIDOC
## License Flow

1. On activation, extension reads key from `context.secrets`
2. If valid: start server (if `autoStart` enabled)
3. If missing/invalid: sidebar shows "License Key Required" item (non-intrusive — no popup)
4. User clicks to enter key via `showInputBox` with format validation
5. Valid key stored in `context.secrets.store('cursorRemote.licenseKey', key)`
6. Key passed to server child process via `LICENSE_KEY` env var
7. Server's own `checkLicense()` validates independently (defense-in-depth)
8. "Buy License" in sidebar opens the store URL with UTM tracking (`?utm_source=extension&utm_medium=sidebar&utm_campaign=license`)
```

--------------------------------

### Release Project

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Manages project releases by bumping the version (patch, minor, or major), updating the changelog, and creating a git tag.

```bash
npm run release -- patch|minor|major
```

--------------------------------

### To-do List Widget Display

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram_prd.md

Presents a to-do list with task statuses. Uses icons: ✅ for completed, 🔵 for in progress, and ⚪ for pending. This widget is purely informational and does not have an inline keyboard.

```html
<b>📝 To-dos (4/10):</b>
✅ BC: Disable Search Partners, keep Display ON
✅ CRM: Disable Display Network
🔵 CRM: Add negative keywords
⚪ CRM: Mark 26 unreviewed search queries
⚪ Update adjustments logs for both campaigns
```

--------------------------------

### Launch Cursor with CDP on Linux

Source: https://github.com/len5ky/cursorremote/blob/main/extension/media/walkthrough/cdp.md

Use this command in the terminal to launch Cursor with the remote debugging port enabled on Linux.

```bash
cursor --remote-debugging-port=9222
```

--------------------------------

### Enable Tailscale Funnel for Port 3000

Source: https://github.com/len5ky/cursorremote/blob/main/docs/tailscale-setup.md

Creates a temporary, public HTTPS URL for accessing a service running on port 3000. The access is public but can be secured with a password. Stop the funnel with Ctrl+C.

```bash
tailscale funnel 3000
```

--------------------------------

### File Structure of Cursor IDE Remote Project

Source: https://github.com/len5ky/cursorremote/blob/main/docs/architecture.md

Overview of the directory and file organization for the cursor-ide-remote project, including source code, documentation, and scripts.

```tree
cursor-ide-remote/
├── docs/
│   ├── initial_prd.md            # Original requirements (preserved)
│   ├── prd.md                    # Comprehensive PRD (this project's spec)
│   ├── architecture.md           # This document
│   ├── telegram_prd.md           # Telegram module PRD
│   └── telegram_architecture.md  # Telegram module architecture
├── temp/                         # Saved DOM snapshots for analysis
│   ├── full.html                 # Full Cursor window DOM
│   ├── chat.html                 # Chat panel DOM only
│   ├── plan_widget.html          # Plan widget DOM snapshot
│   ├── run_widget.html           # Run command widget DOM snapshot
│   └── workbench.desktop.main.css  # Cursor's CSS
├── src/
│   ├── server/
│   │   ├── index.ts              # Entry point: wiring + startup
│   │   ├── config.ts             # Environment config + selector loading
│   │   ├── types.ts              # All shared TypeScript interfaces
│   │   ├── cdp-client.ts         # Lightweight CDP client (raw WebSocket)
│   │   ├── cdp-bridge.ts         # CDP connection lifecycle + reconnection
│   │   ├── dom-extractor.ts      # DOM polling + ChatElement extraction
│   │   ├── command-executor.ts   # CDP action translation
│   │   ├── state-manager.ts      # State diffing + event emission
│   │   ├── relay.ts              # Web transport: Express + socket.io
│   │   └── transports/
│   │       ├── types.ts          # Transport interface
│   │       ├── telegram/
│   │       │   ├── base.ts       # BaseTelegramTransport (shared logic)
│   │       │   ├── tg-types.ts   # Grammy-free types (API, context, keyboard)
│   │       │   ├── index.ts      # Grammy TelegramTransport
│   │       │   ├── formatter.ts  # ChatElement → Telegram HTML
│   │       │   ├── commands.ts   # Bot command handlers
│   │       │   ├── topic-manager.ts  # Topic ↔ window+tab mapping
│   │       └── telegram-raw/
│   │           ├── index.ts      # RawTelegramTransport (no Grammy)
│   │           ├── raw-api.ts    # fetch-based Telegram API client
│   │           └── message-tracker.ts  # Element → message ID tracking
│   ├── client/
│   │   ├── index.html            # SPA shell
│   │   ├── app.js                # Client logic (socket.io, per-type rendering)
│   │   └── styles.css            # Cursor-themed dark styles
│   └── discovery/
│       └── discover-dom.ts       # DOM structure discovery CLI
├── extension/
│   ├── src/
│   │   ├── extension.ts           # VS Code extension entry point
│   │   ├── server-manager.ts      # Child process lifecycle + health polling
│   │   ├── license-manager.ts     # License validation + buy link
│   │   ├── status-bar.ts          # Status bar item
│   │   ├── output-channel.ts      # OutputChannel wrapper
│   │   ├── config-bridge.ts       # VS Code settings → env vars
│   │   └── tree-view.ts           # Sidebar TreeDataProvider
│   ├── media/
│   │   └── icon.png               # Extension icon
│   ├── esbuild.js                 # Extension bundler config
│   └── tsconfig.json              # Extension-specific tsconfig
├── scripts/
│   ├── dev-wrapper.ts             # Dev startup (license prompt)
│   └── release.ts                 # Version bump + changelog + tag
├── selectors.json                # Externalized DOM selectors (user-editable)
├── package.json
├── tsconfig.json
├── CHANGELOG.md
├── .vscodeignore
└── .gitignore
```

--------------------------------

### Server-Side Enhancements

Source: https://github.com/len5ky/cursorremote/blob/main/docs/extension_prd.md

Details backward-compatible changes made to the server to support the extension, including richer endpoints and environment variable configurations.

```APIDOC
## Server-Side Enhancements

Backward-compatible changes to support the extension:

### Richer `/health` endpoint
Returns `windows`, `activeWindowId`, `mode`, `model`, `chatTabCount`, `pendingApprovalCount`, `generation`, `uptime`, `authRequired`. Existing clients ignore unknown fields.

### `LICENSE_KEY` env var
Read license key from `process.env.LICENSE_KEY` before falling back to `data/license.key` file.

### `DATA_DIR` env var
Configurable data directory (default: `./data`). Extension sets this to `context.globalStorageUri.fsPath`.

### `LOG_FORMAT` env var
When set to `json`, emit structured JSON lines to stdout.

### Cache-busting static serving
`GET /` dynamically reads `index.html` and injects `?v=<random>` query parameters on `app.js` and `styles.css` tags. Static files served with `Cache-Control: no-cache, must-revalidate`.

### Auth middleware ordering
`/health` and static files are served before the auth middleware, preventing redirect loops when the web client checks authentication state.

### grammY native fetch
The Telegram bot is constructed with `{ client: { fetch } }` to use Node.js's native `fetch` API. grammY's default HTTP client (based on `node:https` / `node-fetch`) breaks in the esbuild-bundled ESM environment.

### Graceful Telegram shutdown
`bot.stop()` is awaited with a 3-second timeout during server shutdown, ensuring the long-polling session is cleanly closed and the next server instance can connect immediately.

### Telegram connectivity diagnostics
On startup, the server tests outbound HTTPS with raw `fetch` to `api.telegram.org/bot<token>/getMe` and `deleteWebhook`. If unreachable, it tests `google.com` to distinguish between Telegram-specific blocks and general network issues.
```

--------------------------------

### PlanBlock Schema

Source: https://github.com/len5ky/cursorremote/blob/main/docs/prd.md

Defines the structure for plan execution summaries and rich plan widgets.

```APIDOC
## PlanBlock

### Description
Represents a plan execution summary or a rich plan widget.

### Fields
- **id** (string) - Message UUID
- **flatIndex** (number) - Sequential position
- **label** (string) - Plan filename or label badge
- **title** (string) - Plan title
- **todosCompleted** (number) - Number of completed todos
- **todosTotal** (number) - Total number of todos
- **description** (string) - Optional: Plan overview
- **todos** (PlanTodo[]) - Optional: Individual todo items
- **model** (string) - Optional: Model name
- **actions** (PlanAction[]) - Optional: View Plan and Build button selectors
```

--------------------------------

### Package VS Code Extension

Source: https://github.com/len5ky/cursorremote/blob/main/README.md

Increments the patch version and packages the VS Code extension into the 'releases/' directory.

```bash
npm run package
```

--------------------------------

### Inbound Data Flow: Telegram to Cursor (Inline Keyboard Taps)

Source: https://github.com/len5ky/cursorremote/blob/main/docs/telegram_architecture.md

Describes the handling of callback queries from inline keyboard buttons. It details parsing callback data, looking up selectors, and routing actions to `commandExecutor` for approvals, actions, mode, or model changes.

```text
User taps inline keyboard button
  │
  ▼
Bot callback_query handler
  │
  ├─ Parse callback data: "{action}:{shortId}:{selectorHash}"
  │
  ├─ Look up full selectorPath from hash map
  │
  ├─ Route by action:
  │   ├─ approve / reject / approve_all → commandExecutor.clickApproval(selectorPath)
  │   ├─ run / skip / allow → commandExecutor.clickAction(selectorPath)
  │   ├─ build / view_plan → commandExecutor.clickAction(selectorPath)
  │   ├─ set_mode:{modeId} → commandExecutor.setMode(modeId)
  │   └─ set_model:{modelId} → commandExecutor.setModel(modelId)
  │
  └─ Answer callback query with result text
```

--------------------------------

### Cursor State JSONL Format

Source: https://github.com/len5ky/cursorremote/blob/main/docs/cdp-record-replay.md

The structure of each line in the generated recording file.

```json
{"ts":1711234567890,"state":{"connected":true,"agentStatus":"generating","agentActivityText":"Planning next moves","messages":[...],...}}
```