CLI tool
wojciech-kulik/FlashSpace avatar
wojciech-kulik/FlashSpace

FlashSpace: macOS workspaces built on hiding windows

FlashSpace is a blazingly fast virtual workspace manager for macOS ⚡

3,556 stars68 forksSwiftGPL-3.0

At a glance

What is it?
FlashSpace replaces the native macOS Spaces with its own workspaces, and it does that by hiding the windows you did not assign rather than by moving them. That single mechanism explains the feature list, the two dead ends the documentation admits to, and why its Picture-in-Picture support depends on your browser being set to English.
Who is it for?
FlashSpace fits someone who already keeps every app on one macOS Space per display and wants a hotkey to change that set instantly, because that is the workflow it assumes and the one it is built to make faster than the system's own animation. Two things to check before you rely on it.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 20 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • wojciech-kulik/FlashSpace3,556 ★ · +44
Star history
Repository2026-09-242026-11-15
wojciech-kulik/FlashSpace3.5k3.6k

44 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Everything works by hiding windows, because macOS has no API for that

The mechanism is one sentence long and it explains the rest of the project.

You define virtual workspaces and assign apps to them. Each workspace is assigned to a specific display. When you switch to a workspace, the assigned apps are presented and all other apps from that display are hidden. Workspaces can be switched independently on each display.

So this is not a compositor and not a virtual desktop in the X server sense. It hides windows, and it does that on top of the operating system's own Spaces, one macOS Space per display.

The Picture-in-Picture section states the constraint that made this design necessary. macOS does not offer a public API to hide a specific window, and hiding an app also hides its Picture-in-Picture window. So the workaround is to detect whether an app supports Picture-in-Picture and, if it does, hide every window except that one into a screen corner instead of hiding the app. If no Picture-in-Picture window is visible, the standard behaviour applies and the app is hidden normally.

That is a creative response to a missing API, and it also explains the caveats attached to it: the feature is described as experimental and can be switched off in settings, and it may not work if your browser's language is not set to English. Eleven browsers are listed as supported, so the list is broad and the language condition is narrow.

One requirement is a system setting you have to change first

Two requirements are listed, and the second one is the interesting one.

The first is a platform floor: macOS 14.0 or later.

The second is that the Displays have separate Spaces option must be enabled in the Desktop and Dock system settings.

That setting decides whether macOS keeps one desktop per display or consolidates them into a single Space you move between. The first step of the usage instructions depends on it too: you are told to move all your apps to a single macOS Space per display, which is only possible when the setting is on.

So this application asks you to reconfigure the operating system before it can do its job, and then asks you to arrange your windows the way it expects. Both steps are legitimate for a tool built on Spaces, and both are invisible in the sense that nothing in the interface tells you they happened.

The practical consequence for an evaluator is that you cannot judge this on a laptop with the default consolidated setup. If you have ever turned separate Spaces off deliberately, this tool is not for you, and the readme's requirement list is where you find out.

Two display assignment modes, each with a documented dead end

How a workspace maps to a screen is the one place where the documentation admits its own limits, and it is worth reading both entries.

The static mode is the default. Each workspace is assigned to a specific display, which the document compares to how the system's own Spaces work. The stated problem: this mode can be challenging if you use multiple displays and change their arrangement frequently. That is a real cost, because rearranging displays is exactly when you would want to switch workspaces, and static assignment ties a workspace to a screen position.

The dynamic mode assigns each workspace automatically to the displays where its apps are located. One workspace can be shown on multiple displays at the same time, which the document recommends for rearranging workspaces by moving apps between screens without touching configuration. The stated limit is short and absolute: you cannot show empty workspaces in this mode.

That second limitation is a direct consequence of the definition. If a workspace is assigned by where its apps are, then a workspace with no apps has nowhere to be, so it cannot be displayed. A mode that follows your windows cannot show a blank desktop, and the readme says so in one sentence.

The mode can be changed in the application settings, so neither choice is permanent.

The command line interface lives inside the application bundle

The SketchyBar integration is the section that reveals the command line surface, and it is more informative than the feature list.

The integration runs a configurable script when the workspace changes. The configuration example subscribes a status bar item to an event whose name names the workspace change, and the plugin script reads three environment variables: the item name, the current workspace and the current display.

So the contract with external tools is an event plus three variables. That is a small, stable interface, and it is the reason the integration can be written in any language a shell will run.

The second example is where the command line interface appears. To list every workspace, the script invokes a binary inside the application bundle:

bash
WORKSPACES=$(/Applications/FlashSpace.app/Contents/Resources/flashspace list-workspaces)

So the interface is a subcommand of a binary that lives in the application's resources directory, not a separately installed tool. There is no separate formula for it, no entry in the user's path and no version of its own. Anyone scripting against it is reaching into a bundle path, which is stable as long as the bundle layout does not change, and is not a published contract.

The feature list does mention a command line interface as its own item, so the capability is claimed; the readme section that shows it in use is the SketchyBar one.

Nineteen features against five stated values

The project states its values as a list of five principles, and they are worth setting next to the feature list.

Performance, meaning the application should be as fast as possible. Simplicity, meaning it should be easy to use and configure. Reliability, meaning it should work without glitches and unexpected behaviour. Invisible, meaning it should help rather than disturb. And a version of the Unix philosophy: the application should do one thing and do it well, which the document glosses as managing workspaces.

Then the feature list, which has nineteen checked items. Among them: a grid preview of all workspaces, a switcher that works like the system's own application switcher, focus detection that activates a workspace when you focus an app, a focus manager for moving focus between windows, a cursor manager that centres the cursor in the active window, profiles for switching whole configurations, a configurable menu bar item per workspace, trackpad swipe gestures, floating apps that stay visible across workspaces, configuration through both a graphical interface and a file in any of three formats, dynamic display assignment, the command line interface, Picture-in-Picture support, an integration with a status bar tool, and an extension for a launcher written by somebody else.

So the fourth value and the fifth value are in tension with the list. A cursor manager, a menu bar item and a trackpad gesture layer are not invisible, and they are not workspace management in the narrow sense the fifth value claims. That does not make the values dishonest; it makes them a statement of intent against which you can judge the feature list, which is more useful than a list alone.

Three config formats, two linters and a generated project file

The repository's build and tooling files answer the question of how this is put together.

Configuration is offered in three formats: JSON, YAML and TOML. The feature list also says configuration happens through the graphical interface and through a config file, so both routes are supported and the format is your choice.

For the code itself there are two separate tools. One configuration file governs a formatter and another governs a linter, which is the modern Swift pairing and means both formatting and diagnostics are enforced before a commit.

The Xcode project is described twice over. There is a project file checked into the repository and there is a project specification file beside it, which is the pattern for a project generated from a declarative description. Both are present, so the generated artefact and its source are both version controlled.

Then the release machinery. A fastlane directory handles packaging and upload, and a directory named after an automatic update framework holds its configuration, which means the application updates itself rather than waiting for the package manager. There is a Brewfile at the root as well, alongside the cask installation the readme leads with.

So the distribution story has three paths: a package manager, a direct binary download, and in-app updates. Only the first is pinned by a version in the readme.

The patch number is a build counter, not a patch level

Look at the release tags and the versioning scheme becomes visible.

The three newest are 4.16.76, then 4.17.78, then 4.18.79. The minor version increments by one at each release and the final component keeps climbing across those increments: seventy-six, then seventy-eight, then seventy-nine.

A patch number that continues across minor releases is not a patch level. It is a build counter, and the practical effect is that you cannot tell from a version number how much changed between two releases. A jump from one to the next could be a dozen commits or a thousand.

The dates put a rhythm on it. The three releases are dated 2026-04-28, 2026-05-20 and 2026-09-07, and the last recorded push to the default branch is dated 2026-09-17. So the cadence is irregular, with a four-month gap before the most recent one, which is consistent with a project that ships when it has something to ship rather than on a schedule.

For an updater that ships itself through an in-app mechanism, a build counter is a reasonable choice. For anyone writing a dependency constraint or an audit record, it is not much of a version.

Installation is a cask, a download, or a build

Three ways in, and they are listed in the order you would try them.

The first is a single package manager command, and the badge above it points at the cask formula page rather than at a formula, which confirms it is a desktop application cask rather than a library:

bash
brew install flashspace

The second is a download from the releases page, which is also where the project's binaries live for anyone not using the package manager.

The third is building from source, and the readme handles it by linking to a later section rather than inlining the instructions, which is a small sign that the source build is documented separately from the front page.

Nothing on this page pins a version. The command installs whatever the package manager considers current, and the releases page is the only place a specific build is named. For an application that updates itself through an in-app mechanism, that is a coherent arrangement: you install once and the updater handles the rest.

The remaining requirements are the platform floor and the Spaces setting described earlier. There is no mention of a Rosetta requirement, an architecture list, or a system extension to approve, which is worth noting because an application that hides other applications' windows on macOS is doing something the system does not make easy, and the absence of an installer prompt in the requirements list is itself part of the mechanism described in the first section.

Editorial conclusion

FlashSpace fits someone who already keeps every app on one macOS Space per display and wants a hotkey to change that set instantly, because that is the workflow it assumes and the one it is built to make faster than the system's own animation. Two things to check before you rely on it. It needs a system setting changed in advance, separate Spaces per display, so it will not behave on a multi-display setup that has been consolidated. And the core mechanism is window hiding, which is why several features are marked experimental, why empty workspaces cannot be shown in dynamic display mode, and why the Picture-in-Picture path has to move every other window into a corner. The licence is GPL, which matters if you plan to bundle it, and the command line interface lives inside the application bundle rather than as a separate tool.

Frequently asked questions

What is FlashSpace?

A virtual workspace manager for macOS. You define workspaces, assign apps and a display to each, and switching a workspace presents its assigned apps while hiding the other apps on that display. It requires macOS 14 or later and the separate Spaces per display system setting to be enabled.

flashspace alternative

The repository does not list alternatives. Its own positioning is stated as a set of five values, including performance, simplicity, staying invisible, and doing one thing well, which the readme glosses as managing workspaces. Configuration is offered through a graphical interface, a config file in JSON, YAML or TOML, and a command line interface.

flash space vs aerospace

This repository does not compare itself with other workspace managers. The comparison it does make is with the native macOS Spaces feature, which it says it is designed to enhance and replace, and which requires the same system setting to be enabled for either to work as described.

Does FlashSpace support Picture-in-Picture?

Yes, as an experimental feature that can be disabled in the app settings. Because macOS offers no public API to hide a specific window and hiding an app also hides its Picture-in-Picture window, it hides every other window into a screen corner instead. The readme notes the feature may not work if your browser language is not English, and lists eleven supported browsers.

Official sources

  1. Issues
  2. License: GPL-3.0
  3. README
  4. Releases
  5. wojciech-kulik/FlashSpace on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/wojciech-kulik-flashspace.svg)](https://hysenlabs.com/projects/wojciech-kulik-flashspace)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/wojciech-kulik-flashspace.svg)](https://hysenlabs.com/projects/wojciech-kulik-flashspace)

Was this useful?