Break Police

Break Police is a VS Code extension for Windows, macOS, and Linux that checks webcam frames for face presence, counts down configurable work time, and forces a fullscreen break screen.

Platform note: Break Police only works in a local desktop VS Code window. It will refuse to activate in remote/web sessions. On Windows the break screen is a native PowerShell WPF overlay; on macOS and Linux it's a fullscreen Electron window.

Privacy

• All webcam frames are processed locally by the bundled companion app; nothing is uploaded, recorded to disk, or sent anywhere.
• The extension only reports whether a face is present, never the image itself, back to the VS Code extension host.

What it does

• Verifies that a webcam can be opened when the extension starts.
• Starts a configurable 45 minute work timer that only counts down while a face is visible in camera frames.
• Samples frames every 5 seconds by default and also checks immediately after each timer reset.
• Shows a warning notification 10 seconds before the break screen appears.
• Opens a fullscreen break window with a large message, a 15 minute countdown, and a disabled restart button.
• Resets the next work cycle after the break countdown finishes and the user clicks the restart button.

Notes

• Webcam monitoring runs in a bundled Electron companion app.
• On Windows, the fullscreen break window is shown by a native PowerShell WPF overlay. On macOS and Linux, it's a fullscreen kiosk-mode Electron window. All of them block normal window-closing interactions, but a user-space application cannot guarantee that every operating-system shortcut is blocked. Ctrl+Alt+Del (Windows), Cmd+Option+Esc / Cmd+Q (macOS), and compositor-level shortcuts (Linux) remain outside the extension's control. On Wayland in particular, always-on-top/kiosk behavior depends on the compositor and may be less strict than on X11.
• On macOS, the first time the companion app opens the camera, System Settings will prompt for camera access under the "Electron" app name. Approve it in System Settings > Privacy & Security > Camera; if you deny it, re-enable it there and restart VS Code.
• On macOS, npm install patches a camera usage description into the bundled Electron.app and then re-signs the bundle ad-hoc. Editing anything inside an app bundle invalidates its code signature, and on Apple Silicon an invalidly signed binary is killed on launch. If the companion ever fails to start after a reinstall, re-sign it manually with codesign --force --sign - --deep node_modules/electron/dist/Electron.app.
• On Linux, there's no OS-level permission prompt for the camera; access depends on standard device permissions (your user account typically needs to be in the video group, or have read/write access to /dev/video*).
• Chromium's native face-detection API (used on Windows and macOS) has no Linux implementation, so on Linux the companion app instead runs a bundled MediaPipe Face Detector (the BlazeFace short-range model) locally in the renderer via WebAssembly. It never sends frames anywhere; detection stays on-device just like the native path. This adds roughly 23 MB to the packaged extension (the WASM runtime, in both SIMD and no-SIMD variants for safety, plus the model file) versus the Windows/macOS builds.
• Detection is not identical across platforms. The MediaPipe fallback is more willing to report a face than the native detector, and presence is decided by OR-ing six overlapping crops of each frame, which compounds that. A false "present" reading keeps the work timer running while you are away. If that happens, raise MEDIAPIPE_MIN_CONFIDENCE in resources/companion/monitor.js — it is set explicitly to 0.5 rather than left implicit so it is easy to find and tune.
• On Linux the companion runs with --no-sandbox. Chromium's setuid sandbox needs a root-owned chrome-sandbox helper, which an extension unpacked into your user profile cannot provide, so Electron would otherwise refuse to start. The companion only ever loads local files shipped with the extension.
• Wayland substantially weakens break enforcement. globalShortcut registration is a no-op under Wayland, and kiosk mode, always-on-top, and focus-stealing are all at the compositor's discretion, so the break window can be dismissed or switched away from in ways it cannot be on Windows, macOS, or X11. Treat the Linux/Wayland break screen as a strong reminder rather than an enforced lock.

Settings

• breakPolice.workDurationMinutes
• breakPolice.warningSeconds
• breakPolice.breakDurationMinutes
• breakPolice.faceSampleSeconds

Local development

1. Run npm install (on macOS this also patches the bundled Electron.app's Info.plist with a camera usage description, and on every platform it prunes the unused MediaPipe WASM variant; see Notes above).
2. Run npm run compile.
3. Press F5 in VS Code to launch an Extension Development Host.

Install In Normal VS Code Windows

Build and install natively on the OS you want to run the extension on, since the packaged .vsix bundles whatever platform-specific Electron binary npm install fetched for the current machine:

1. Run npm install.
2. Run npm run install:vsix.
3. Reload VS Code when prompted.

That installs <publisher>.break-police into your normal local VS Code profile, so it will activate automatically in regular desktop windows after startup. npm run package:vsix alone produces a break-police-<target>.vsix (e.g. break-police-win32-x64.vsix, break-police-darwin-arm64.vsix, or break-police-linux-x64.vsix) without installing it.

Packaging caveat (macOS/Linux, still worth validating on real hardware): shipping Electron inside a VSIX is not as safe as it looks. A VSIX is a ZIP, and two things can be lost in the round trip:

• The executable bit. The extension defensively restores it at spawn time (chmod 755 on the Electron binary, chrome-sandbox, and chrome_crashpad_handler) if it is missing, so this should self-heal.
• Symlinks. Electron.app on macOS contains symlinks inside Contents/Frameworks/*.framework (Versions/Current and friends). @vscode/vsce's zip writer doesn't just drop these — it throws (not a file) and aborts packaging entirely. npm install's macOS postinstall step (scripts/patch-macos-electron-plist.js) now flattens each framework's symlinks into real copies, deletes the now-redundant Versions/ directory, and re-signs the bundle, so vsce package/vsce publish succeed without manual intervention. Still worth an actual launch test on real Mac hardware before publishing a darwin-* target, since this only verifies the bundle packages and re-signs cleanly, not that every code path works.

Publishing to the Marketplace

1. Set publisher in package.json to your registered Marketplace publisher ID (create one first if you don't have one, and a matching Azure DevOps personal access token).
2. Run npx @vscode/vsce login <publisher-id> once, then authenticate with your token.
3. Because the bundled Electron binary is platform-specific, package and publish a separate target per OS/architecture, built natively on that OS:

   # on Windows
   npx @vscode/vsce package --target win32-x64 --allow-missing-repository
   npx @vscode/vsce publish --target win32-x64 --allow-missing-repository
   
   # on Apple Silicon macOS
   npx @vscode/vsce package --target darwin-arm64 --allow-missing-repository
   npx @vscode/vsce publish --target darwin-arm64 --allow-missing-repository
   
   # on Intel macOS
   npx @vscode/vsce package --target darwin-x64 --allow-missing-repository
   npx @vscode/vsce publish --target darwin-x64 --allow-missing-repository
   
   # on Linux (x64)
   npx @vscode/vsce package --target linux-x64 --allow-missing-repository
   npx @vscode/vsce publish --target linux-x64 --allow-missing-repository
   
   # on Linux (arm64)
   npx @vscode/vsce package --target linux-arm64 --allow-missing-repository
   npx @vscode/vsce publish --target linux-arm64 --allow-missing-repository
   

4. Bump the version in package.json and update CHANGELOG.md before each release.