|
| 1 | +# Quick Start Guide - AppSwitcher Stream Deck Plugin |
| 2 | + |
| 3 | +**For Users:** Jump straight to using the plugin |
| 4 | +**For Developers:** Quick commands to build and test |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +## For Users |
| 9 | + |
| 10 | +### Installation |
| 11 | + |
| 12 | +**Prerequisites:** |
| 13 | +1. AppSwitcher installed and running |
| 14 | +2. Stream Deck software installed |
| 15 | +3. Stream Deck hardware connected |
| 16 | + |
| 17 | +**Check if Plugin is Installed:** |
| 18 | +```powershell |
| 19 | +dir "$env:APPDATA\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin" |
| 20 | +``` |
| 21 | + |
| 22 | +If not installed, see [Development Guide](DEVELOPMENT.md#deployment). |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +### Using the Plugin |
| 27 | + |
| 28 | +**Step 1: Configure AppSwitcher Slots** |
| 29 | + |
| 30 | +1. Open AppSwitcher (toolbar at top of screen) |
| 31 | +2. Right-click empty slot → **Assign Active Window** |
| 32 | +3. Or: Press **Ctrl+Alt+1** to assign to Slot 1, **Ctrl+Alt+2** for Slot 2, etc. |
| 33 | +4. Repeat for as many slots as you want |
| 34 | + |
| 35 | +**Step 2: Add Buttons to Stream Deck** |
| 36 | + |
| 37 | +1. Open Stream Deck software |
| 38 | +2. Find **"AppSwitcher Slot"** in the actions list |
| 39 | +3. Drag to any button on your Stream Deck |
| 40 | +4. Repeat for multiple buttons (all default to Slot 0 currently) |
| 41 | + |
| 42 | +**Step 3: Press Button to Activate** |
| 43 | + |
| 44 | +- Press button → Window activates |
| 45 | +- Green flash = Success |
| 46 | +- Red flash = Error (slot empty or window not found) |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +### Common Tasks |
| 51 | + |
| 52 | +**Assign Active Window to Slot:** |
| 53 | +- Make window active (click it) |
| 54 | +- In AppSwitcher: Right-click slot → Assign Active Window |
| 55 | +- Or: Press **Ctrl+Alt+[1-9]** |
| 56 | + |
| 57 | +**Change Slot Assignment:** |
| 58 | +- Just assign a new window to the same slot |
| 59 | +- Previous assignment is replaced |
| 60 | + |
| 61 | +**Remove Slot Assignment:** |
| 62 | +- In AppSwitcher: Right-click slot → Clear |
| 63 | + |
| 64 | +**Check What's in a Slot:** |
| 65 | +- Look at AppSwitcher toolbar |
| 66 | +- Or run: `apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_SLOT:0` |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## For Developers |
| 71 | + |
| 72 | +### Quick Build |
| 73 | + |
| 74 | +```bash |
| 75 | +# Build AppSwitcher with IPC |
| 76 | +cd apps/AppSwitcher |
| 77 | +dotnet publish -c Release -r win-x64 --self-contained true |
| 78 | + |
| 79 | +# Build Stream Deck Plugin |
| 80 | +cd ../AppSwitcher.StreamDeck |
| 81 | +dotnet publish -c Release -r win-x64 --self-contained false |
| 82 | + |
| 83 | +# Build Test Client |
| 84 | +cd ../AppSwitcher.TestClient |
| 85 | +dotnet publish -c Release |
| 86 | +``` |
| 87 | + |
| 88 | +--- |
| 89 | + |
| 90 | +### Quick Install |
| 91 | + |
| 92 | +```powershell |
| 93 | +# Install plugin to Stream Deck |
| 94 | +cd apps/AppSwitcher.StreamDeck |
| 95 | +
|
| 96 | +$dest = "$env:APPDATA\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin" |
| 97 | +New-Item -ItemType Directory -Force -Path $dest |
| 98 | +
|
| 99 | +Copy-Item -Path "bin\Release\net8.0\win-x64\publish\*" -Destination $dest -Recurse -Force |
| 100 | +Copy-Item -Path "com.appswitcher.sdPlugin\manifest.json" -Destination $dest -Force |
| 101 | +Copy-Item -Path "com.appswitcher.sdPlugin\*.png" -Destination $dest -Force |
| 102 | +
|
| 103 | +# Restart Stream Deck |
| 104 | +cd ..\.. |
| 105 | +.\restart-streamdeck.bat |
| 106 | +``` |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +### Quick Test |
| 111 | + |
| 112 | +```bash |
| 113 | +# Start AppSwitcher |
| 114 | +start apps\AppSwitcher\bin\x64\Release\net8.0-windows\win-x64\publish\AppSwitcher.exe |
| 115 | + |
| 116 | +# Test IPC |
| 117 | +.\test-quick.ps1 |
| 118 | + |
| 119 | +# Or manual test |
| 120 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe PING |
| 121 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_SLOT:0 |
| 122 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe ACTIVATE:0 |
| 123 | +``` |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +### Quick Debug |
| 128 | + |
| 129 | +**AppSwitcher IPC Server:** |
| 130 | +- Set breakpoint in `StreamDeckBridge.cs` |
| 131 | +- F5 in Visual Studio |
| 132 | + |
| 133 | +**Stream Deck Plugin:** |
| 134 | +- Stream Deck → Help → Open Stream Deck Debug |
| 135 | +- Look for `AppSwitcher.StreamDeck.exe` logs |
| 136 | + |
| 137 | +**IPC Communication:** |
| 138 | +```bash |
| 139 | +# Test without Stream Deck |
| 140 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe PING |
| 141 | +``` |
| 142 | + |
| 143 | +--- |
| 144 | + |
| 145 | +## File Locations |
| 146 | + |
| 147 | +### Plugin Files |
| 148 | +``` |
| 149 | +%APPDATA%\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin\ |
| 150 | +├── manifest.json |
| 151 | +├── AppSwitcher.StreamDeck.exe |
| 152 | +├── *.dll (dependencies) |
| 153 | +└── *.png (icons) |
| 154 | +``` |
| 155 | + |
| 156 | +### AppSwitcher Config |
| 157 | +``` |
| 158 | +%APPDATA%\AppSwitcher\ |
| 159 | +├── config.json (slot assignments) |
| 160 | +├── favicon_*.png (website icons) |
| 161 | +└── clipicon_*.png (custom icons) |
| 162 | +``` |
| 163 | + |
| 164 | +### Stream Deck Logs |
| 165 | +``` |
| 166 | +Help → Open Stream Deck Debug |
| 167 | +``` |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +## Common Commands |
| 172 | + |
| 173 | +### IPC Test Commands |
| 174 | + |
| 175 | +```bash |
| 176 | +# Health check |
| 177 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe PING |
| 178 | + |
| 179 | +# Get configuration |
| 180 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_STATE |
| 181 | + |
| 182 | +# Get slot info |
| 183 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_SLOT:0 |
| 184 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_SLOT:5 |
| 185 | + |
| 186 | +# Activate slot |
| 187 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe ACTIVATE:0 |
| 188 | + |
| 189 | +# Assign active window to slot |
| 190 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe ASSIGN_ACTIVE:3 |
| 191 | +``` |
| 192 | + |
| 193 | +### PowerShell Commands |
| 194 | + |
| 195 | +```powershell |
| 196 | +# Check if AppSwitcher is running |
| 197 | +Get-Process -Name "AppSwitcher" -ErrorAction SilentlyContinue |
| 198 | +
|
| 199 | +# Check if Stream Deck is running |
| 200 | +Get-Process -Name "Stream Deck" -ErrorAction SilentlyContinue |
| 201 | +
|
| 202 | +# View AppSwitcher config |
| 203 | +Get-Content "$env:APPDATA\AppSwitcher\config.json" | ConvertFrom-Json |
| 204 | +
|
| 205 | +# Verify plugin installation |
| 206 | +Test-Path "$env:APPDATA\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin\manifest.json" |
| 207 | +
|
| 208 | +# Kill and restart AppSwitcher |
| 209 | +Stop-Process -Name "AppSwitcher" -Force -ErrorAction SilentlyContinue |
| 210 | +Start-Process "apps\AppSwitcher\bin\x64\Release\net8.0-windows\win-x64\publish\AppSwitcher.exe" |
| 211 | +``` |
| 212 | + |
| 213 | +--- |
| 214 | + |
| 215 | +## Troubleshooting Quick Fixes |
| 216 | + |
| 217 | +### Plugin Not Showing |
| 218 | +```bash |
| 219 | +# Restart Stream Deck |
| 220 | +.\restart-streamdeck.bat |
| 221 | + |
| 222 | +# Verify plugin files |
| 223 | +dir "$env:APPDATA\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin" |
| 224 | + |
| 225 | +# Check manifest syntax |
| 226 | +Get-Content "$env:APPDATA\Elgato\StreamDeck\Plugins\com.appswitcher.sdPlugin\manifest.json" | ConvertFrom-Json |
| 227 | +``` |
| 228 | + |
| 229 | +### Button Not Working |
| 230 | +```bash |
| 231 | +# Check if AppSwitcher is running |
| 232 | +tasklist | findstr AppSwitcher |
| 233 | + |
| 234 | +# Test IPC |
| 235 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe PING |
| 236 | + |
| 237 | +# Check slot |
| 238 | +apps\AppSwitcher.TestClient\bin\Release\net8.0\AppSwitcher.TestClient.exe GET_SLOT:0 |
| 239 | + |
| 240 | +# Restart AppSwitcher |
| 241 | +taskkill /F /IM AppSwitcher.exe |
| 242 | +start apps\AppSwitcher\bin\x64\Release\net8.0-windows\win-x64\publish\AppSwitcher.exe |
| 243 | +``` |
| 244 | + |
| 245 | +### IPC Connection Failed |
| 246 | +```bash |
| 247 | +# Verify AppSwitcher is running |
| 248 | +Get-Process -Name "AppSwitcher" |
| 249 | + |
| 250 | +# Rebuild AppSwitcher with IPC |
| 251 | +cd apps\AppSwitcher |
| 252 | +dotnet publish -c Release -r win-x64 --self-contained true |
| 253 | + |
| 254 | +# Restart AppSwitcher |
| 255 | +taskkill /F /IM AppSwitcher.exe |
| 256 | +start bin\x64\Release\net8.0-windows\win-x64\publish\AppSwitcher.exe |
| 257 | + |
| 258 | +# Test again |
| 259 | +.\test-quick.ps1 |
| 260 | +``` |
| 261 | + |
| 262 | +--- |
| 263 | + |
| 264 | +## Project Structure Quick Reference |
| 265 | + |
| 266 | +``` |
| 267 | +worktools/ |
| 268 | +├── .claude/ 📁 Documentation (you are here) |
| 269 | +│ ├── README.md Overview |
| 270 | +│ ├── QUICKSTART.md This file |
| 271 | +│ ├── ROADMAP.md Future plans |
| 272 | +│ ├── ARCHITECTURE.md Technical details |
| 273 | +│ ├── IPC-API.md IPC commands |
| 274 | +│ └── DEVELOPMENT.md Dev guide |
| 275 | +│ |
| 276 | +├── apps/ |
| 277 | +│ ├── AppSwitcher/ Main application |
| 278 | +│ │ ├── StreamDeckBridge.cs IPC server |
| 279 | +│ │ └── MainWindow.xaml.cs UI + IPC integration |
| 280 | +│ │ |
| 281 | +│ ├── AppSwitcher.TestClient/ IPC test utility |
| 282 | +│ │ └── Program.cs |
| 283 | +│ │ |
| 284 | +│ └── AppSwitcher.StreamDeck/ Stream Deck plugin |
| 285 | +│ ├── IpcClient.cs IPC client |
| 286 | +│ ├── ConfigMonitor.cs File watcher |
| 287 | +│ ├── Program.cs Plugin logic |
| 288 | +│ └── com.appswitcher.sdPlugin/ Plugin package |
| 289 | +│ |
| 290 | +├── test-quick.ps1 Quick IPC test |
| 291 | +└── restart-streamdeck.bat Restart helper |
| 292 | +``` |
| 293 | + |
| 294 | +--- |
| 295 | + |
| 296 | +## Next Steps |
| 297 | + |
| 298 | +**Users:** |
| 299 | +1. Configure your favorite apps in AppSwitcher slots |
| 300 | +2. Add buttons to Stream Deck |
| 301 | +3. Enjoy quick app switching! |
| 302 | + |
| 303 | +**Developers:** |
| 304 | +1. Read [ROADMAP.md](ROADMAP.md) for planned features |
| 305 | +2. Review [ARCHITECTURE.md](ARCHITECTURE.md) for technical details |
| 306 | +3. See [DEVELOPMENT.md](DEVELOPMENT.md) for implementation guide |
| 307 | + |
| 308 | +--- |
| 309 | + |
| 310 | +## Quick Links |
| 311 | + |
| 312 | +- **Full Documentation:** See other files in `.claude/` folder |
| 313 | +- **IPC API Reference:** [IPC-API.md](IPC-API.md) |
| 314 | +- **Bug Reports:** Check Stream Deck logs (Help → Open Stream Deck Debug) |
| 315 | +- **Source Code:** `apps/AppSwitcher.StreamDeck/` |
| 316 | + |
| 317 | +--- |
| 318 | + |
| 319 | +## Status Summary |
| 320 | + |
| 321 | +**✅ Working:** |
| 322 | +- IPC communication via Named Pipes |
| 323 | +- Stream Deck plugin functional |
| 324 | +- Button press activates windows |
| 325 | +- Visual feedback (green/red flash) |
| 326 | +- Real-time config monitoring |
| 327 | + |
| 328 | +**⚠️ Limitations:** |
| 329 | +- All buttons default to Slot 0 (no per-button configuration yet) |
| 330 | +- Icons not dynamically loaded from slots |
| 331 | +- Labels don't sync with AppSwitcher slot labels |
| 332 | + |
| 333 | +**🎯 Next Priority:** |
| 334 | +- Property Inspector UI for slot selection (see [ROADMAP.md](ROADMAP.md) Phase 3.1) |
| 335 | +- Dynamic icon loading (see [ROADMAP.md](ROADMAP.md) Phase 3.2) |
| 336 | + |
| 337 | +--- |
| 338 | + |
| 339 | +**Last Updated:** October 10, 2025 |
| 340 | +**Version:** 1.0.0 |
| 341 | +**Status:** Production Ready ✅ |
0 commit comments