GitHub - vrn21/monitor-toggle: MacOS utils app that toggles between Mirrored and Extended for external displays

3 min read Original article ↗

A minimal macOS menu bar app to switch between Extended and Mirror workflows.

Quick Start · What It Does · Download Demo

Watch Demo Video

If inline playback is not supported in your viewer, open the demo link above.

Caution

This video is a synthetic demo generated by Claude. The actual product is a real macOS menu bar app (Monitor Toggle App) that provides these display mode solutions.

What this app does

Monitor Toggle App gives you one-click display mode switching from the macOS menu bar.

  • Extended: your normal multi-screen layout.
  • Mirror: focus on a single mirrored/internal workspace (menu action: Switch to Internal Only).
  • Restore Extended: quickly return to your multi-screen layout.

Why use it

This is useful in more than one scenario:

  • external monitor power drops
  • quick focus mode on one screen
  • joining calls/presentations and simplifying your display setup
  • recovering your layout after dock/cable reconnect changes

Quick start

1) Install dependency

brew install displayplacer

2) Build and package

xcrun swift build -c release
./scripts/package_app.sh

3) Install and launch

After launch, the app runs in the background as a menu bar utility (no terminal required).
Use Quit from the app menu to fully stop it.

Everyday usage

  1. Click Monitor Toggle App in the menu bar.
  2. Use Switch to Internal Only when you want Mirror/focus mode.
  3. Use Restore Extended when you want your multi-screen layout back.
  4. Optional: enable Auto-restore when external returns.
  5. Optional: enable Launch at login.

How I personally use it

When my power connection to Monitor stops (due to some outage) Mac still extends it display. So I'd either need to unplug my hdmi or go change it to mirror from settings (which takes too much time tbh), with this app I just hit Switch to Internal Only, keep working on my MacBook screen, and later click Restore Extended when everything is stable again.

Raycast integration

Script commands are in raycast/:

  • raycast/monitor-toggle-toggle.sh
  • raycast/monitor-toggle-internal-only.sh
  • raycast/monitor-toggle-restore-extended.sh
  • raycast/monitor-toggle-status.sh

All commands use the same core app logic.

Headless actions

./.build/release/monitor-toggle-app --action status
./.build/release/monitor-toggle-app --action toggle
./.build/release/monitor-toggle-app --action internal-only
./.build/release/monitor-toggle-app --action restore-extended
./.build/release/monitor-toggle-app --action rebuild

Paths

  • Config: ~/Library/Application Support/MonitorToggleApp/config.json
  • Logs: ~/Library/Application Support/MonitorToggleApp/logs/app.log

Troubleshooting

  • If restore fails, use Re-detect and rebuild profiles.
  • If external display is not detected, reconnect cable/dongle once, then rebuild.
  • If dependency is missing, install with brew install displayplacer.

Security and distribution note

Current packaging is ad-hoc signed for local/dev distribution.
For broad consumer distribution: use Developer ID signing + notarization + dependency integrity pinning.

License

This project is licensed under the MIT License. See LICENSE.

Regenerate demo media

xcrun swift ./scripts/generate_demo_video.swift