Stream Deck + control surface for Cursor: IDE approve/skip/press-to-talk, plus SDK-first multi-agent status on the touch strip.
packages/plugin— thin Elgato Stream Deck plugin (keys, dials, LCD)packages/bridge— localhost daemon (IDE keystrokes, Cursor SDK registry, usage)packages/shared— WebSocket protocol types
Stream Deck+ → plugin ⇄ ws://127.0.0.1:3210/deck ⇄ bridge
├─ Cursor IDE (keystrokes)
├─ @cursor/sdk agents (status)
└─ usage API (optional)
- macOS 13+
- Node.js 22+ (Stream Deck plugin packaging prefers Node 20/24 per Elgato tooling)
- Stream Deck app 6.9+ with a Stream Deck +
- Cursor desktop app
- Cursor API key for SDK spawn (
CURSOR_API_KEY)
task install # or: npm install
npm run build -w @streamdeck-ai/bridge
# keep bridge alive across reboots (recommended):
cp deploy/com.freerun.streamdeck-ai.bridge.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.freerun.streamdeck-ai.bridge.plist
# or one-shot: task bridgeIn another terminal (with Stream Deck app running):
# install CLI once
npm i -g @elgato/cli
# link/build plugin
cd packages/plugin
npm run build
streamdeck link com.freerun.streamdeck-ai.sdPlugin
npm run watchThen in the Stream Deck app, drag the Cursor AI actions onto your Stream Deck + profile (see docs/profile.md).
Created automatically at ~/.config/streamdeck-ai/config.json:
{
"port": 3210,
"cursorApiKey": "YOUR_CURSOR_API_KEY",
"cursorSessionToken": "…",
"defaultCwd": "/path/to/repo",
"modelId": "auto"
}Set the key in cursorApiKey in ~/.config/streamdeck-ai/config.json, or export CURSOR_API_KEY.
modelId is optional — if omitted, the bridge picks from Cursor.models.list() (prefers auto / auto-smart).
Environment overrides: see .env.example.
| Field | Purpose |
|---|---|
cursorApiKey |
Required for Spawn / Cancel SDK agents |
modelId |
Optional SDK model id (must exist in your catalog) |
cursorSessionToken |
Optional cache for Usage dial — auto-filled from Cursor login via Link Usage (docs/usage-setup.md) |
defaultCwd |
Workspace for SDK agents spawned from the deck |
shortcuts.* |
Override Approve/Skip/Allowlist/PTT/Focus Agents keystrokes |
| Control | Action |
|---|---|
| Approve | Enter in Cursor (approve terminal command) |
| Skip | Esc |
| Allowlist | Shift+Enter |
| PTT | Hold Cursor native voice (Ctrl+M) |
| Focus Agents | Configurable shortcut (default Cmd+Shift+A) |
| Cancel | Not for IDE chats (use Skip/Esc) — alert only |
| Spawn | Optional advanced: clipboard → SDK agent (separate from IDE) |
| Link Usage | Pull usage auth from Cursor IDE login |
| Refresh | Re-read IDE composers + usage |
| Status dial | Rotate = cycle IDE chat; compact W/R/D + name |
| Workspace dial | Rotate = filter chats by project |
| Usage dial | Push = Link when needed / toggle detail |
Status truth: live sessions come from ~/.cursor/projects/*/agent-transcripts (plus glass.selectedAgent). Titles use IDE overview names from composerData; workspace dial uses real folder names. Press the Status or Workspace dial to switch the IDE to the dial selection, then PTT/Approve. See docs/ide-status.md.
Approve / Skip / PTT control the IDE UI. Cancel is not available for IDE chats.
IDE keys (Approve / Skip / PTT / etc.) are injected from the Stream Deck plugin process. Enable Accessibility for Elgato Stream Deck if macOS prompts.
The plugin retries for ~15s if Cursor is mid-restart/update (launches Cursor if needed, clears stuck PTT hold state).
Cursor updates/restarts often. The deck is built to tolerate that:
- IDE actions wait/retry until Cursor is running again
- PTT hold state is cleared if Cursor dies mid-hold
- Bridge command errors no longer kill the daemon
- Plugin↔bridge WebSocket reconnects automatically
cp deploy/com.freerun.streamdeck-ai.bridge.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.freerun.streamdeck-ai.bridge.plistEdit the plist paths first if your checkout is not under ~/Documents/freerun/streamdeck-ai.
task test
task build
task bridge:dev
task plugin:watch