English | 한국어
Back to your work, in one action.
Keep code and reference material together as Checkout, then switch to PR review when a review comes in. Sideby groups the desktops on your Mac and external displays into named workspaces, so you can return without switching every screen yourself. It also works with a single display.
Sideby 0.12.0 adds desktop names, a quick matrix you open by holding a shortcut, and a menu that stays with you while switching.
▶ Watch the film · 21 seconds · Sound on · Still image
21-second brand film — Interrupted. Never lost.: English MP4 · 한국어 MP4 · 9:16 for Shorts and Reels: English · 한국어. From “Where was I?” to three displays returning to the work you left at once. Sideby screens are captured from the actual app with sample data; the desktops on the displays are illustrations. Original score.
Download Sideby · macOS 14 or later · English and Korean
See the 10-second switching demo
Checkout → PR review → Checkout, using the same ⌥⇧Tab shortcut. The MacBook, two external displays and their contents are fictional; transitions illustrate the workflow, not measured hardware performance. View the still image.
- Switch a whole task. Choose a workspace’s Go button to move its assigned desktops on the selected displays.
- Return with the same shortcut. Press
⌥⇧Tabto return to the previous workspace. Press it again to switch back. - Arrange work from the menu. Open Sideby in the menu bar to see the matrix immediately. Rename workspaces, change assignments, or rebuild from the current desktop order there. The matrix stays open as you switch.
Actual Sideby interface rendered with sample workspaces and display data.
Columns are workspaces. Rows are displays. Each cell shows that display’s assigned desktop, including a content label when one is available.
| Action | Result |
|---|---|
| Edit the name at the top of a column | Rename that workspace. Use Go below it to switch. |
| Drag a cell to an empty cell in the same display row | Move the desktop assignment. |
| Drag a cell onto an occupied cell in the same row | Swap the two assignments. |
| Hold Option and drag to an empty cell in the same row | Keep the original assignment and use that desktop in another workspace too. |
| Drag a display’s name or up/down icon | Reorder display rows. |
| Open a cell’s menu | Assign a desktop without dragging, or give that desktop a name. The same desktop shares its name across workspaces. |
Desktop changes are detected automatically. To start over, choose Rebuild from current desktops… at the top of the menu or Workspaces & Displays settings. Sideby confirms how many workspaces it will create, then replaces the selected displays’ names and assignments in current desktop order. This also replaces custom swaps and shared-desktop assignments. Other displays’ assignments are kept separately. Immediately after rebuilding, Undo in the completion message restores the previous configuration when its desktops are still available. The menu has no permanent restore button.
New names use available app/window content from each display’s desktops, including desktops you are not currently viewing. These are suggestions, not native macOS Space names; Sideby falls back to a desktop number when metadata is unavailable. Workspace names you edit are preserved during routine updates; an explicit rebuild creates fresh workspace names. Custom desktop names are separate: they stay attached to the same desktop through reordering, restarting and rebuilding. Choose Use automatic name in its cell menu to return to content suggestions. These names appear only in Sideby, not Mission Control.
Display connection changes are checked automatically. Disconnected display choices and assignments are retained for reconnection; you can continue working with the selected displays that are currently available.
See the full Workspaces & Displays settings
The same matrix is available in All settings → Workspaces & Displays. Input, Permissions, and General settings have their own panes.
- Install and allow access. Download the DMG from GitHub Releases, move Sideby to Applications, and open it. Follow the guide for Accessibility and Screen Switching access.
- Choose your displays. Click the display diagram or checkboxes. One display is enough; a round trip needs two different desktop arrangements. The guide points you to Mission Control if more desktops are needed.
- Name your workspaces. Read the desktop arrangement, name two workspaces, and check which content belongs to each display.
- Go there, then come back. Follow the guide’s buttons to visit the other workspace and return. Finish with Open Sideby menu. You can use shortcuts or gestures afterward.
You can continue the guide later. Its completion is based on a successful round trip; a skipped step or a failed move does not count.
See workspace preparation and the completed round trip
These are production views rendered with sample data, including a simulated completed guide.
| Input | Action |
|---|---|
Hold ⌥⇧Space |
Show the quick matrix; click a workspace to switch. Release the keys or press Escape to close it. |
⌥⇧Tab |
Return to the previous workspace; repeat to alternate between the last two. |
⌥⇧1 … ⌥⇧9, ⌥⇧0 |
Go to workspace positions 1–10. |
⌥⇧< / ⌥⇧> |
Previous / next workspace. |
| Option + Shift + horizontal swipe | Switch with the default gesture. |
For numbered, previous/next and return shortcuts, release Option and Shift to execute the move. For the held matrix, keep the shortcut pressed while clicking a workspace. Change or disable its shortcut in Settings → Input, where you can also configure gestures.
Sideby reads the live desktop layout and checks requested moves. Routine additions, removals, and reordered desktops are reflected automatically while the matrix is open and checked before switching. Saved workspaces follow the same surviving desktops across an app restart; reordering desktops does not reset custom workspace assignments. Workspaces that only use disconnected displays are hidden from the everyday matrix and do not take a shortcut position.
If an older version’s assignments already point at the wrong desktops, use Rebuild from current desktops… once to start again in the current order. Older versions did not save enough identity information to recover a desktop’s previous position after the fact.
If a move is incomplete, Sideby can retry the displays that have not reached the destination. If a required desktop is missing or its layout cannot be read, check the assignment in the menu, or rebuild to start over. The previous setup stays saved if a desktop needed for restoration is missing.
Workspaces refer to existing macOS desktops. Sideby does not reopen documents or restore window contents and positions. Deleting a workspace removes its Sideby assignments, never the macOS desktops themselves.
Sideby uses Accessibility for its configured global gesture and, when available, app/window title suggestions. Screen Switching access allows it to send the requested desktop-switch commands. Some command paths also need System Events Automation. Switching and desktop discovery do not request Screen Recording permission.
Global keyboard registrations cover Option + Shift + number / < / > / Tab and the configurable held-matrix shortcut (default ⌥⇧Space). Sideby checks release of the held shortcut to dismiss its matrix; it does not save typed input. Runtime desktop discovery uses read-only macOS layout queries. Numeric runtime Space IDs, window IDs, raw input events, and screenshots are not saved. Minimal desktop identity bookmarks are stored locally so assignments can follow the same desktops after a restart.
Workspace names and assignments, custom desktop names, the previous setup saved before a rebuild, display choices and row order, remembered display names, input preferences, and guide progress stay locally on your Mac. A content suggestion used as a workspace name becomes part of that saved name.
The direct-distribution app uses private SkyLight APIs with App Sandbox off; it is not targeting the Mac App Store. Updates are delivered through Sparkle 2, with user-approved installation.
Open Package.swift in Xcode with a Swift 6 toolchain, or run:
swift test
swift build --product SidebyApp
swift build --product SidebyDevAppSidebyApp is the product. SidebyDevApp is a local probe and API test harness. To build an app bundle for manual verification, check the published Sparkle feed and run scripts/build_app_bundle.sh with SIDEBY_BUILD_NUMBER set to the latest sparkle:version plus one. Do not use the script’s default build number after a public release exists.
Native screenshots use isolated sample data and can be regenerated without real external displays. See README media for the capture command and asset details. Film production sources are maintained locally; MP4s are distributed as GitHub Release attachments.
SidebyApp: menu bar, windows, product onboarding, and application coordination.SidebyCore: pure Swift workspace, gesture, settings, and recovery rules.SidebySystem: macOS input, display, layout, and command adapters.SidebyUI: reusable SwiftUI views and view models.SidebyDevApp/SidebyDevSupport: local probes and diagnostics.
Space switching goes through ContextSwitchEngine and SpaceCommandExecutor. SwiftUI owns reusable interfaces; AppKit handles menu bar, window, and system integration.
See Development and Decisions for implementation and distribution details.
Read CONTRIBUTING.md before opening an issue or pull request, and run swift test for code changes. Discuss changes involving permissions, input, switching, packaging, or distribution in an issue first.
Report vulnerabilities through the process in SECURITY.md, not a public issue. Sideby is released under the MIT License.