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, resize, and focus windows when you select them. Without this, Macscope can show windows but can't activate or manage them.

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.

Arrangements & Scopes

Macscope is more than a switcher—it's a window manager. Arrange multiple windows into perfect layouts for any task, and save those layouts as "Scopes" for instant recall.

Multi-Selection

To start arranging, you first need to select multiple items.

Mouse: Hold Shift and click on multiple windows or applications.
Keyboard: Hold Shift and use the arrow keys (↑ ↓ ← →) to extend your selection.

                  Creating an Arrangement
                  
                      1. Select Items: Select two or more
                      windows you want to arrange.
                    
                      2. Enter Arrangement Mode: Press
                      ↩ (Enter). The interface will change to show
                      available layouts.
                    
                      3. Choose a Layout: Click or use arrow
                      keys to select a layout (e.g., Vertical Split, 2x2 Grid).
                      Macscope will instantly resize and position your windows.

Saving Arrangements as Scopes (Coming Soon)

After creating an arrangement, you'll be able to name and save it as a Scope. This will let you instantly restore that exact set of windows and their layout with a single click.

Window Management

Beyond switching and arranging, Macscope provides tools to manage and declutter your workspace quickly.

Closing Windows & Quitting Apps

With any window, tab, or application selected in Macscope, press ⌘ + W.

If a window or tab is selected, it will be closed.
If an application (from the fallback search) is selected, the application will be quit.

Maximizing Windows

You can configure Macscope to maximize a window to fill its current display. This can be set as the default action for a click or Enter, or as the alternate action by holding ⌘. See the Settings Guide for more details.

Hiding Items (Exclusions)

If there are certain apps or windows you never want to see in Macscope, you can hide them. Right-click any item and choose "Hide". You can manage your hidden items in the "Exclusions" tab in Settings.

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	`↑` `↓` `←` `→`
Extend Selection	`Shift` + `↑` `↓` `←` `→`
Cycle Items	`Tab`
Select Item / Enter Arrangement	`↩` (Enter)
Maximize Item	`⌘` + `↩` (or as configured)
Close Item / Quit App	`⌘` + `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 (+).