StageHand

Bind helper scripts and automations to specific apps on Windows — launched when the app starts or gains focus, killed when it closes.

StageHand is a tiny Windows tray app that watches what you're doing and runs the right helpers at the right time. When you open OneNote, your drawing shortcut script starts; when you close it, the script stops. When you focus your art app, your tablet switches to the right active area; when you switch back to your note-taking app, it switches back. No macros, no manual toggles, no stale background processes hanging around after you're done.

Features

• App-bound script launching. Point StageHand at a process (e.g., ONENOTE.EXE) and a script (.ahk, .exe, .py, .pyw, .bat, .cmd), pick a mode, and the script's lifecycle follows the app's.
• Two launch modes.
  • App Start — fires when the process is detected running, kills when the process exits. Good for background helpers that should be alive for the whole session.
  • Window Focus — fires when the window gains focus, kills when it loses focus. Good for shortcut scripts that should only be active while you're in the app.
• OpenTabletDriver preset switching. If you use OpenTabletDriver, StageHand can switch presets based on the focused app — useful for swapping active areas, pressure curves, or button maps between drawing and note-taking.
• Settings GUI. Right-click the tray icon → Settings. No JSON editing required (though the file is there if you want it).
• Graceful shutdown. Quitting from the tray menu cleans up all managed subprocesses and restores your default OTD preset.

Example use cases

• Auto-launch an AutoHotkey script with drawing shortcuts when OneNote opens — see examples/onenote-huion.
• Run a microphone-unmuter helper while a specific game is focused.
• Switch your drawing tablet's active area when you swap between your art app and your note-taking app.
• Launch OBS scene helpers only while OBS is in the foreground.
• Bind any .ahk / .exe / .py / .pyw / .bat / .cmd to any process.

Requirements

• Windows 10 or 11
• Python 3.10+
• Optional: AutoHotkey v2 — auto-detected; only needed if you run .ahk scripts.
• Optional: OpenTabletDriver — only needed if you want per-app preset switching.

Install

git clone https://github.com/MrMcEpic/stagehand.git
cd stagehand
pip install .

Or run directly from the clone without installing:

pip install pystray Pillow customtkinter
# then double-click stagehand.pyw, or:
pythonw stagehand.pyw

Quick start

1. Launch StageHand — double-click stagehand.pyw, or run pythonw -m stagehand.
2. A gray circle appears in your system tray titled StageHand — Watching.
3. Right-click the tray icon → Settings.
4. Under App Launch Rules, click + Add App.
5. Enter the process name (e.g., NOTEPAD.EXE — Windows process names are case-insensitive but convention is uppercase).
6. Choose a launch mode: App Start or Window Focus.
7. Click + Add Script and browse to the script or program you want bound to that app.
8. Click Save.
9. Open the target app. Your script launches. Close it. Your script stops. Done.

When any managed script is running, the tray icon turns green.

Launch modes

App Start

Fires on process start, kills on process exit. StageHand polls running processes every ~2 seconds. If your script dies while the app is still running, StageHand relaunches it on the next tick.

Use for: long-running background helpers, process-wide daemons, anything that should live as long as the app does.

Window Focus

Fires when the app's window becomes the foreground window, kills when it loses focus. StageHand polls the foreground window ~3 times per second, so response is near-instant.

Use for: shortcut scripts, context-sensitive hotkey layouts, anything that should only be active while you're actually interacting with the app. Multiple apps can be in window_focus mode and their scripts will cleanly hand off as you switch windows.

Configuration

Most people never need to touch the config file — the settings GUI covers everything. If you want to edit it by hand, see docs/configuration.md for the full field reference.

The config file lives next to the launcher (stagehand.pyw) by default, as watcher_config.json. It's auto-created on first save.

Examples

• examples/onenote-huion — Huion tablet + OneNote drawing shortcut layout. Binds a set of AutoHotkey hotkeys (pen/eraser/lasso tool switching via pen buttons) to OneNote, with OTD preset switching.

How it works

StageHand runs two threads:

1. Tray thread — pystray icon with a Settings/Quit menu.
2. Watcher thread — ~3 Hz loop that reads the foreground process, polls tasklist every ~2 s for app-start mode rules, and launches/kills subprocesses based on state transitions. When any managed subprocess is running, the tray icon goes green.

Configuration lives in a JSON file next to the launcher, edited through a CustomTkinter-based settings window opened from the tray menu. OpenTabletDriver integration is optional and degrades to a no-op if the OTD CLI isn't found.

License

MIT — see LICENSE.