WinMux is an intuitive, sidebar-first window manager for macOS. It began as an AeroSpace-derived codebase, but its runtime model is being reshaped around WinMux projects, workspaces, displays, tab groups, and sidebar workflows.
demo.mp4
An agent mode is in the works, read about it here and see a demo—this is just for fun right now (dont expect anyone would use it), but still interesting to see.
The sidebar is a more interactively-performant and useful (though less customizable—WIP!) alternative to Sketchybar and traditional workspace menu bar dropdowns for most everyday tasks. It provides better visibility into spaces and spatial awareness on the desktop.
You can drag windows in and out of the sidebar from and to the current workspace. You can rearrange windows across all spaces using the sidebar, including tab groups.
The sidebar can be configured (as shown) to display the current date, time, battery, sound, and network interface (things that I used to have in sketchybar).
Tab groups allow you to have many windows occupy the same footprint, similar to Yabai stacks but with browser-like tab behavior. This is useful when you want to have multiple pieces of reference information next to an editor, multiple tabs in different browser profiles, or, when you simply want multiple fullscreen views without the additional friction and overhead of creating a new workspace.
Unlike stack-only layouts, WinMux tab groups behave more intuitively like you would expect tabs to in browsers, and don't need a keyboard shortcut to activate. You can drag tabs from tab groups into another window's intent zone, or in between workspaces. You can also rearrange tab order within a tab group, and navigate through them with relative and absolute keybindings.
WinMux has 6 intent (hover-hint) zones that make it easy to move windows without keyboard shortcuts:
- Left/Right/Up/Down split
- Form Tab Group (drag over top of a window)
- Swap positions with window (drag over center)
You do not need to open up a config file to change shortcuts for basic actions. More advanced actions still require editing of the config file (~/.config/winmux/winmux.toml). You can also edit, validate and reload the config file from within the settings!
WinMux comes with it's own mission-control-expose that shows you all the windows and tab groups in the current workspace. Trigger it with ⌃+i
Multiple displays are managed. Each display can show its own visible workspace, and the sidebar can be scoped to the focused display, all displays, or a specific display.
You can NOT create workspaces that have no windows in them. Workspaces with no windows are automatically destroyed.
WinMux supports single-modifer keybindings (e.g. triggering an action on press of ⌘)
I highly recommend that you configure the apps you use every day to be launch with Left/Right Option+Command, or similar shortcuts. Here is some of the apps that I have keybinded:
[mode.main.binding-tap]
left-alt = 'exec-and-forget /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --profile-directory="Default"'
right-cmd = 'exec-and-forget /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --profile-directory="Profile 1"'
[mode.main.binding]
# Disable the native "Hide App" shortcut.
cmd-h = []
cmd-d = 'exec-and-forget osascript ~/Documents/scripts/launchTerminalWindow.scpt'
cmd-e = 'exec-and-forget osascript ~/Documents/scripts/launchFinderWindow.scpt'# ~/Documents/scripts/launchTerminalWindow.scpt
tell application "cmux"
if it is running
tell application "System Events" to tell process "cmux"
click menu item "New Window" of menu "File" of menu bar 1
end tell
else
activate
end if
end tell
# ~/Documents/scripts/launchFinderWindow.scpt
tell application "Finder"
if it is running
tell application "System Events" to tell process "Finder"
click menu item "New Finder Window" of menu "File" of menu bar 1
end tell
else
activate
end if
end tell
WinMux started from AeroSpace, but the goal is not to keep AeroSpace as the product model. Runtime behavior should be expressed in WinMux concepts: projects, workspaces, displays, monitors, tab groups, and sidebar state.
The eventual goal is still to keep exploring lower-level backends such as Yabai where it makes sense, but WinMux should not depend on old AeroSpace names or compatibility fallbacks in normal operation.
Download the latest binary from releases and launch.
As WinMux is not signed, you will need to bypass gatekeeper:
xattr -dr com.apple.quarantine /Applications/WinMux.app/If ~/.config/winmux/winmux.toml already exists, WinMux uses it as-is.
If it does not exist and an AeroSpace config exists, WinMux imports that config once into ~/.config/winmux/winmux.toml, translating known AeroSpace-era names into current WinMux syntax. After that, WinMux reads the generated WinMux config and does not keep syncing or falling back to the AeroSpace source file.
If neither exists, WinMux creates a new WinMux config with the bundled defaults.
The importer translates:
accordionlayouts totab-grouph_accordion/v_accordionlayout commands toh_tab_group/v_tab_groupaccordion-paddingtotab-group-paddingAEROSPACE_*workspace/window environment variables toWINMUX_*
After importing an AeroSpace config, add the WinMux-specific features you want with a block like this:
window-tabs.enabled = true
window-tabs.height = 36
[workspace-sidebar]
enabled = true
collapsed-width = 44
width = 240
monitor = 'main'
# Reserve room for the visible macOS menu bar so the sidebar is not covered by the Apple menu.
# Use 0 when the macOS menu bar auto-hides.
menu-bar-reserve-height = 28
show-status-pills = true
show-date = trueNew WinMux bootstrap configs include menu-bar-reserve-height = 28 by default. Imported AeroSpace configs are migrated, but the importer only translates known compatibility names; add this key manually or set it from Settings if your sidebar starts underneath the macOS menu bar.
Release builds use XcodeGen/Xcode
Build, archive, zip, and publish a GitHub release:
make release VERSION=0.1.0The release build uses automatic signing with your local Apple Development certificate and team configured in the Makefile.
To build the release artifact without publishing to GitHub:
make release VERSION=0.1.0 PUBLISH=0You can report issues via Menu Bar > Report an Issue on Github. Please consider contributing!!
- Tab groups
- Sidebar
- Workspace renaming
- Sidebar customization/plugins system
- Support for Yabai
- Integrate trackpad swiping support (see some work I did on JiTouch)
The app logo/icon is still Aerospace's and will proab stay that way for a while. Been focusing on getting everything working first.