Skip to content

Add optional Windows unattended-run toolkit (hidden autostart + QR-recovery watchdog) - #284

Open
jorgeschnura wants to merge 1 commit into
lharries:mainfrom
jorgeschnura:windows-unattended-scripts
Open

Add optional Windows unattended-run toolkit (hidden autostart + QR-recovery watchdog)#284
jorgeschnura wants to merge 1 commit into
lharries:mainfrom
jorgeschnura:windows-unattended-scripts

Conversation

@jorgeschnura

Copy link
Copy Markdown

This PR adds an optional windows/ folder with a small, self-contained toolkit that makes the Go whatsapp-bridge run reliably unattended on Windows, plus a WINDOWS.md docs page linked from the existing "Windows Compatibility" section of the README.

It is purely additive: nothing that works today on macOS/Linux changes, and the Python MCP server and Go bridge are untouched. It only adds the Windows process-management layer around them.

Why Windows needs this

Running the bridge unattended on Windows hits three practical gaps:

  1. The bridge must be a user process, not a service. whatsmeow links WhatsApp Web's multi-device session in the interactive user context. Run the bridge as a LocalSystem service and it starts, but its :8080 REST port never opens, so the MCP server has nothing to connect to. Running it as the logged-in user is the only configuration that reliably brings :8080 up.
  2. A permanent visible console is undesirable. As a user process it normally leaves a terminal open forever (easy to close by accident). These scripts run it hidden.
  3. The QR is only needed occasionally. WhatsApp sometimes unlinks a device and the bridge waits for a fresh QR. Showing a window on every restart is noise. The watchdog discriminates: it silently recovers ordinary crashes and only surfaces a visible QR window (plus a Windows notification) when bridge.log actually shows the session is unlinked.

What's added

  • windows/start-whatsapp-hidden.vbs — launches the bridge hidden, fire-and-forget.
  • windows/start-whatsapp-bridge.bat — auto-restart loop; UTF-8 console so a logged QR stays legible; writes bridge.log.
  • windows/qr-bridge.bat — runs the bridge in a visible window so the QR is scannable.
  • windows/whatsapp-bridge-watchdog.ps1 — recover-first watchdog (:8080 check, silent relaunch, QR window + notification only when truly unlinked).
  • windows/install.ps1 — registers hidden autostart (at-logon scheduled task or Startup shortcut) + the watchdog scheduled task; parameterized with -WhatsAppMcpDir, with a matching -Uninstall.
  • WINDOWS.md — step-by-step Windows setup, assuming the Go bridge is already built.
  • A short pointer added under the README's existing "Windows Compatibility" section.

Notes

  • No script hard-codes a path; they resolve the install dir from the WHATSAPP_MCP_DIR env var or their own location.
  • Everything runs in the interactive user session by design; there is no headless/service mode, because :8080 only opens as a user process (that is the whole reason this exists).
  • The watchdog matches the bridge's current QR log strings (Timeout waiting for QR, Scan this QR code); if that wording ever changes, one line updates.
  • All PowerShell parses cleanly; MIT-licensed, consistent with the repo.

Happy to adjust naming, folder placement, or the README link to fit the project's conventions. A standalone version also lives at whatsapp-mcp-windows for users who find it before this lands.

…dog)

Adds a windows/ folder and a WINDOWS.md docs page (linked from the existing
Windows Compatibility section) that make the Go whatsapp-bridge run reliably
unattended on Windows. Purely additive: the Python MCP server and Go bridge are
unchanged; nothing on macOS/Linux is affected.

Contents:
  windows/start-whatsapp-hidden.vbs    launch the bridge hidden, no-wait
  windows/start-whatsapp-bridge.bat    auto-restart loop, UTF-8 console, log
  windows/qr-bridge.bat                visible window to scan the QR
  windows/whatsapp-bridge-watchdog.ps1 recover-first watchdog
  windows/install.ps1                  register hidden autostart + watchdog task
  WINDOWS.md                           step-by-step Windows setup

Why: the bridge only opens :8080 as an interactive user process (not as a
LocalSystem service); running it hidden with auto-restart and a watchdog that
only surfaces the QR when the session is truly unlinked closes that gap. No
script hard-codes a path (WHATSAPP_MCP_DIR env var or script-relative).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant