Skip to content

About

Stream Deck + control surface for Cursor IDE and SDK agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

streamdeck-ai

Stream Deck + control surface for Cursor: IDE approve/skip/press-to-talk, plus SDK-first multi-agent status on the touch strip.

Architecture

  • 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)

Requirements

  • 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)

Quick start

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 bridge

In 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 watch

Then in the Stream Deck app, drag the Cursor AI actions onto your Stream Deck + profile (see docs/profile.md).

Config

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

Controls

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.

Accessibility

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 restarts

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

Optional: start bridge at login

cp deploy/com.freerun.streamdeck-ai.bridge.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.freerun.streamdeck-ai.bridge.plist

Edit the plist paths first if your checkout is not under ~/Documents/freerun/streamdeck-ai.

Develop

task test
task build
task bridge:dev
task plugin:watch

Manual checklist

See docs/manual-checklist.md.

About

Stream Deck + control surface for Cursor IDE and SDK agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages