Macscope Documentation

Everything you need to master the ultimate window switcher for macOS.

Installation

Download the latest Macscope release, open the .dmg file, and drag the Macscope app into your /Applications folder.

Permissions Setup

On first launch, Macscope guides you through granting essential system permissions required for its core functionality.

Accessibility

Required to move and focus windows when you select them. Without this, Macscope can show windows but can't activate them when selected.

Screen Recording

Required for live window previews. Your screen content is never stored or transmitted.

Automation (Optional)

Required for browser tab listing and control. This allows Macscope to list and switch between browser tabs.

Important: If you skip permissions during setup, you can grant them later through System Settings. Macscope will work with limited functionality until they are granted.

Universal Search

The core of Macscope is its powerful search functionality. It's designed to find and switch to what you need with the minimum number of keystrokes, eliminating the need to memorize complex shortcuts.

Automatic Activation

As you type, Macscope filters all open windows and tabs. When your search query is specific enough to narrow the results to a single item, Macscope automatically activates it—no need to even press Enter.

Fallback to App Launcher

If your search doesn't match any open windows or tabs, Macscope will suggest a list of installed applications you can launch. Please note that Macscope is designed as a window switcher, not a primary application launcher; this feature is a convenience fallback.

Quick Switch & Locking

For users accustomed to the traditional Cmd+Tab workflow, the Quick Switch feature provides a simple way to toggle between recent applications, which can be enhanced with App Locking.

Tap vs. Hold Behavior

Quick Tap: Instantly switch to your previously active (or locked) application.
Hold (0.25s): Open the full Macscope interface to search and browse all windows.

The hold duration is customizable in settings (0.15s - 1.0s).

Enhancing Quick Switch with App Locking

You can make the "Quick Tap" action even more powerful by locking your most-used apps.

                  How App Locking Works
                  
                      Lock up to 2 apps: Perfect for common
                      workflows like editor + browser.
                    
                      Instant Toggling: When two apps are
                      locked, a quick tap of the shortcut will alternate
                      directly between them, ignoring other recent apps.

Workflow Tip: Right-click any window to lock its parent application. Lock your code editor and a browser to make the "Tap" shortcut an incredibly fast way to switch between coding and previewing your work.

Browser Tab Integration

Access all your browser tabs directly from Macscope, just like native windows. Supported browsers include Safari, Chrome, Arc, Edge, Brave, and more.

Multi-Display Support

Macscope is designed for multi-screen workflows, offering powerful tools to manage windows across all your displays.

                  Key Multi-Display Features
                  
                      Mouse-Aware Activation: By default,
                      Macscope appears on whichever display your mouse cursor is
                      currently on.
                    
                      Simultaneous View: An optional setting
                      allows Macscope to appear on all displays at once for a
                      complete overview.
                    
                      Focused Display: In simultaneous view,
                      the active display is highlighted, and you can switch
                      focus by hovering your mouse or using keyboard shortcuts.
                    
                      Move Windows: Optionally, you can
                      configure selected applications to automatically move to
                      your active display upon activation.

Experimental Feature: The "Show on all displays" mode is still in development and may not work as expected in all configurations.

Keyboard Shortcuts

Macscope is designed for keyboard-first workflows. All global shortcuts can be customized in Settings.

Action	Shortcut(s)
Navigate Items	`↑` `↓` `←` `→`
Cycle Items	`Tab`
Select Item	`↩` (Enter)
Close Item	`⌘` + `W`
Lock/Unlock Item	`⌘` + `L`
Switch Display Focus (Multi-Display)	`Shift`+`Tab`

Settings Guide

Customize Macscope to match your workflow with these comprehensive settings.

General

Launch Macscope at login

Starts the app automatically when you log in to your Mac.

Show icon in menu bar

Toggles the visibility of the Macscope icon in the system menu bar.

List open browser tabs

Includes tabs from supported browsers in the search results.

Show on all displays

Renders the Macscope UI on all connected monitors simultaneously.

Move app to active display

Relocates application windows to the current monitor upon selection.

Behavior & Shortcuts

Open as a full-screen overlay

Changes the UI from a centered window to an immersive, full-screen experience.

Enable Quick Switch

Enables the Tap (quick switch) vs. Hold (show UI) functionality for the global shortcut.

Hold Duration

Fine-tunes the delay required to register a "hold" action for the global shortcut.

Shortcuts

Configure the global hotkeys for showing, locking, and closing items in the Shortcuts tab.

Troubleshooting

If you encounter issues, refer to these common solutions.

Browser tabs aren't showing up

This is a permissions issue. Go to System Settings → Privacy & Security → Automation, find Macscope, and ensure it's enabled for your browsers.

Live previews are black or frozen

This is a screen recording permission issue. Go to System Settings → Privacy & Security → Screen Recording, remove Macscope (-), then add it again (+).