🖥️ Stream Deck Shell

Run any shell command — or a full script — directly from a Stream Deck button on macOS.
Type your commands in the property inspector, press the key, done.

---

What it does

Each Stream Deck button gets its own multiline command editor. Type your commands (one per line), press the key, and choose how they run:

Mode	Behaviour
🖥 Show	macOS Terminal opens visually and runs your commands. Optionally closes when done.
👻 Hidden	Commands run silently in the background — no window, no noise. Just ✅ or ⚠️ on the key.

---

Features

• Multiline command editor — as many commands as you need, one per line
• Show / Hidden terminal toggle — visible or silent execution per button
• Real shell execution — zsh or bash, so pipes, &&, variables, and env paths all work
• Auto-close option — Terminal window closes itself after the last command (Show mode)
• Comment support — lines starting with # are skipped
• set -e in hidden mode — execution stops on first error and flashes ⚠️
• Visual feedback — ✅ on success, ⚠️ on error or empty config
• macOS only — built exclusively for macOS via AppleScript + direct shell exec

---

How it works under the hood

The plugin is written in TypeScript using the Elgato Stream Deck SDK v3. It runs as a Node.js process managed by the Stream Deck application and communicates via WebSocket.

Show mode

keyDown → read settings → write /tmp/sd-shell-xxx.sh
       → osascript → Terminal.app opens
       → (optional) poll busy state → close window
       → delete temp script after 10s

Hidden mode

keyDown → read settings → write /tmp/sd-shell-hidden-xxx.sh
       → execFile("/bin/zsh", [scriptPath])
       → awaits exit code
       → delete temp script immediately
       → showOk ✅ or showAlert ⚠️

┌───────────────────────────────────────────────────────────┐
│  Stream Deck hardware (USB/BT)                            │
└──────────────────────┬────────────────────────────────────┘
                       │ keyDown (WebSocket)
┌──────────────────────▼────────────────────────────────────┐
│  plugin.js  (Node.js, managed by SD app)                  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  RunShellAction.onKeyDown()                         │  │
│  │   → read settings (commands, shell, terminalMode)  │  │
│  │   → write temp .sh script to /tmp/                 │  │
│  │                                                     │  │
│  │   terminalMode === "show"                           │  │
│  │     → execFile("osascript") → Terminal.app         │  │
│  │                                                     │  │
│  │   terminalMode === "hide"                           │  │
│  │     → execFile("/bin/zsh", [scriptPath])           │  │
│  │     → silent, no window                            │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

---

Installation

See INSTALL.md for full setup instructions.

TL;DR — for developers:

git clone https://github.com/paulfxyz/stream-deck-shell.git
cd stream-deck-shell
npm install
npm run build
cp -r com.paulfleury.shell.sdPlugin \
  ~/Library/Application\ Support/com.elgato.StreamDeck/Plugins/

---

Usage

1. Open Stream Deck.
2. Find Stream Deck Shell in the Actions panel (under Developer Tools).
3. Drag Run Shell Commands onto any key.
4. Click the key to open the Property Inspector.
5. Type your commands — one per line.
6. Choose Show (Terminal opens) or Hidden (silent background run).
7. Choose your shell (zsh or bash) and whether to close Terminal after (Show mode only).
8. Press the physical key on your deck.

Example commands

# Restart a local dev server (hidden — no window needed)
pkill -f "node server.js"
cd ~/Projects/myapp && npm run dev

# Quick git push (show — see the output)
cd ~/Projects/myapp && git add -A && git commit -m "wip" && git push

# Open your favourite apps (hidden — just fire and forget)
open -a "Spotify"
open -a "Slack"
open -a "Figma"

# macOS notification after a hidden task
osascript -e 'display notification "Build finished!" with title "Stream Deck Shell"'

---

Project Structure

stream-deck-shell/
├── com.paulfleury.shell.sdPlugin/   ← compiled plugin (install this)
│   ├── bin/
│   │   └── plugin.js               ← compiled entry point
│   ├── imgs/                        ← SVG icons
│   ├── ui/
│   │   └── inspector.html          ← property inspector UI
│   └── manifest.json               ← plugin metadata & actions
├── src/
│   ├── actions/
│   │   └── run-shell.ts            ← core action logic (show + hidden modes)
│   └── plugin.ts                   ← entry point & action registration
├── package.json
├── rollup.config.mjs
├── tsconfig.json
├── README.md
├── INSTALL.md
└── CHANGELOG.md

---

Contributing

PRs are welcome. Open an issue first for anything beyond a bugfix.

git clone https://github.com/paulfxyz/stream-deck-shell.git
cd stream-deck-shell
npm install
npm run watch   # builds on save, hot-reloads into Stream Deck

---

Roadmap

• Windows support (PowerShell + cmd)
• Custom button icon derived from first command
• Multi-action grouping (chain N buttons as a sequence)
• iTerm2 support as alternative terminal
• Environment variable injection per-button
• Warp terminal support
• Notification on hidden mode completion (native macOS alert)

---

License

MIT — Paul Fleury, 2026

---

Disclaimer — 100% Vibe Coding

A candid note: I'm not a software engineer by trade. I'm a former hacker turned Internet entrepreneur who has a very good relationship with AI and tools like Claude and Perplexity Computer. This plugin was designed and built through pure conversation with AI assistants — no IDE gymnastics, no Stack Overflow spelunking. Just describing what I wanted until it worked.