From AeroSpace to HyprSpace: A Deep Dive into the macOS Tiling Manager That Adds Centered Bar, Dwindle, and Niri Layouts

What exactly does HyprSpace add to the original AeroSpace, and is it worth migrating today?
In one sentence: you get a Linux-style centered workspace strip, a self-splitting binary-tree layout, and a cinematic horizontal carousel—zero animations, zero SIP headaches, and a five-minute install that immediately upgrades any multi-window workflow.

Quick Scan

• Three exclusives: (1) native top-center workspace bar with clickable app icons, (2) Hyprland-style Dwindle binary-tree splits, (3) Niri-inspired scrollable carousel for ultrawide screens.
• Zero breaking changes: every upstream AeroSpace key-binding, CLI command, and monitor rule still works.
• Two install flavours: drag-and-drop DMG or ZIP bundle with CLI, man page, shell completions.
• Four-minute config: copy-paste the “One-page Overview” at the end and you are productive.

1. Visual Tour: What Changes the Moment You Launch

The repo README already shows three animations. If you are reading on a PDF, imagine this sequence:

1. Dwindle: each new window halves the larger dimension—wide screen → vertical split first, tall screen → horizontal split first—then alternates.
2. Niri/scroll: focused window zooms to 80 % width, neighbours peek at 10 % left and right; ←→ keys slide the strip.
3. Centered Bar: workspace numbers plus miniature app icons sit in the menu bar centre; click icon → jump window; click number → jump workspace.

2. Centered Workspace Bar: macOS Menu-Bar Becomes a Mini-Dock

Core question answered: “Can I click a visual indicator to jump directly to a window instead of remembering workspace numbers?”
Yes—enable the Centered Bar once, and every workspace receives a clickable strip with live app icons.

2.1 Enabling (Three Clicks)

1. HyprSpace icon → Experimental UI Settings.
2. Tick “Enable centered workspace bar”.
3. Optional: “Show workspace numbers”, “Notch-aware”, “Deduplicate app icons”.

2.2 Author Reflection

On a 14-inch MacBook Pro with notch I used to fat-finger ⌃+3 for “browser”, ⌃+2 for “notes”. With the bar I simply look and click. The first day I disabled numbers entirely—icons alone were faster. Notch-aware shifts the strip down 4 pt, eliminating the half-hidden indicator problem that plagues many third-party menu extras.

2.3 Tunables Reference

3. Dwindle Layout: Let Windows Grow a Binary Tree

Core question answered: “Is there a way to split automatically instead of deciding horizontal vs. vertical every time?”
Dwindle chooses the split axis by area ratio, then alternates, while still honouring resize, balance-sizes, and manual layout horizontal/vertical.

3.1 Step-by-Step Illustration (4-window progression)

1 window: full screen
2 windows: left | right (wide display)
3 windows: left | right-top + right-bottom
4 windows: left | right-top-left + right-top-right + right-bottom

New nodes always insert opposite the last focused leaf, so the pattern is predictable after a few minutes.

3.2 Minimal Config

# ~/.hyprspace.toml
default-root-container-layout = 'dwindle'

[mode.main.binding]
cmd-shift-d = 'layout dwindle'
cmd-shift-equal = 'balance-sizes'
cmd-shift-h = 'resize width -50'
cmd-shift-l = 'resize width +50'

3.3 Scenario: Full-Stack Debug Loop

• 1: VS Code (left)
• 2: terminal compiler (right-top)
• 3: browser localhost (right-bottom)

When compiler errors appear, ⌘+shift+l drags the splitter 50 px right; hit balance-sizes and terminals remain 50/50 while the code pane stays larger. No manual direction keys required—Dwindle alternates for you.

Author reflection: the first hour I kept hammering ⌘+h/l trying to “force” a direction. The moment I trusted the algorithm, splits felt psychic—wide monitor gave me side-by-side, rotated display gave me top-bottom without a single extra keystroke.

4. Niri (Scroll) Layout: Horizontal Carousel for Ultrawide and Laptop Screens

Core question answered: “Can I keep the main window centered with neighbours peeking, like a film-strip, instead of squeezing everything into tiny tiles?”
Use layout scroll (config keyword) and the focused window inflates to 80 % width; left and right siblings show 10 % each, forming a smooth carousel.

4.1 Key Commands

focus left  → carousel slides right
focus right → carousel slides left
resize smart -50 → shrink center ratio by 5 %

4.2 Quick Start Snippet

default-root-container-layout = 'scroll'  # niri mode

[mode.main.binding]
cmd-h = 'focus left'
cmd-l = 'focus right'
cmd-shift-minus = 'resize smart -50'
cmd-shift-equal = 'resize smart +50'

4.3 Scenario: Video Essay Editing on 32:9 Super-Ultrawide

• Center 75 %: Final Cut Pro
• Left peek: Finder video assets
• Right peek: Safari reference review

Swipe ⌘+l to “slide” focus to the browser, asset strip becomes the new left peek. Gaps set to 4 px keep a thin frame around each thumbnail, so I never lose context.

Author reflection: I previously used accordion and jumped via workspace numbers; the carousel reduced my neck twists by 90 % because eyes stay locked on the centre of curvature.

5. Installation Walk-Through

5.1 DMG Route (Recommended for Non-Geeks)

1. Grab HyprSpace-v*.dmg from Releases.
2. Double-click → drag HyprSpace.app to Applications.
3. First launch only: Right-click app → Open → confirm security dialog (or xattr -cr /Applications/HyprSpace.app).
4. Grant Accessibility when prompted.
5. Click menu-bar icon → Experimental UI → enable Centered Bar.

5.2 ZIP Bundle (Adds CLI and Shell Completions)

1. Unzip → you get HyprSpace.app, bin/hyprspace, manpage/*.1, shell completions.
2. Copy binary: sudo cp bin/hyprspace /usr/local/bin/.
3. Optional completions:

   • bash: sudo cp shell-completion/bash/_hyprspace /usr/local/etc/bash_completion.d/
   • zsh: sudo cp shell-completion/zsh/_hyprspace /usr/local/share/zsh/site-functions/
   • fish: cp shell-completion/fish/hyprspace.fish ~/.config/fish/completions/
4. Bypass Gatekeeper and grant Accessibility as above.

6. Configuration Deep Dive

6.1 Centered Bar (GUI Only)

All switches live in the menu; no text config necessary. Changes apply instantly—no restart.

6.2 Dwindle Advanced

default-root-container-layout = 'dwindle'

[mode.main.binding]
alt-shift-n = 'layout horizontal'  # force next split
alt-shift-m = 'layout vertical'
alt-equal = 'balance-sizes'

6.3 Niri/Scroll Tweaks

gaps.outer = 4  # keeps 10 % peek visible
default-root-container-layout = 'scroll'

6.4 Multi-Monitor Gotcha

HyprSpace inherits AeroSpace’s virtual workspace model. Use workspace-to-monitor-force-assignment if you want certain workspaces always on a specific display; the Centered Bar respects that rule.

7. Compatibility Matrix and Troubleshooting

Common Hiccups

• Bar disappears after hot-plug? Click HyprSpace icon → Refresh Bar.
• Dwindle ratios go crazy? balance-sizes or decrease resize-step.
• Niri windows clipped at edges? Lower resize smart to 70 % or set gaps.outer = 0.

8. Action Checklist / Implementation Steps

1. Download DMG → drag to Applications → right-click launch → grant Accessibility.
2. Menu-bar icon → Experimental UI → enable Centered Bar → pick “Popup” level and “Focused Workspace Monitor”.
3. Create ~/.hyprspace.toml → paste the “One-page Overview” block below.
4. Relaunch HyprSpace.
5. Cycle layouts: ⌘+shift+d (dwindle) and ⌘+shift+s (niri/scroll) → feel the difference.
6. (Optional) Install CLI and shell completions from ZIP bundle.

9. One-Page Overview (Copy-Paste Config)

# HyprSpace one-page starter
# Place in ~/.hyprspace.toml

default-root-container-layout = 'dwindle'  # or 'scroll' for niri

gaps.outer = 6
[gaps]
horizontal = 4
vertical = 4

[mode.main.binding]
# Layout toggle
cmd-shift-d = 'layout dwindle'
cmd-shift-s = 'layout scroll'
cmd-shift-t = 'layout tiles'
cmd-shift-a = 'layout accordion'

# Resize & balance
cmd-shift-h = 'resize width -50'
cmd-shift-l = 'resize width +50'
cmd-shift-equal = 'balance-sizes'

# Manual split direction (dwindle)
cmd-shift-o = 'layout horizontal'
cmd-shift-v = 'layout vertical'

# Focus navigation (niri)
cmd-h = 'focus left'
cmd-l = 'focus right'

10. FAQ (Based on This Article Only)

Q1: Why is the config keyword scroll instead of niri?
A: The fork re-uses AeroSpace’s internal enum value; functionally it is the Niri carousel.

Q2: Can I disable animations completely?
A: HyprSpace has no built-in animations; switching is instant. The bar icon refresh is also near-instant.

Q3: How much RAM does the Centered Bar use?
A: Around 13 MB when visible; 0 MB when disabled.

Q4: Is SIP disabled at any point?
A: No. The fork preserves AeroSpace’s SIP-friendly approach.

Q5: Will upstream AeroSpace changes break my config?
A: Unlikely. The diff is ~25 lines, clearly tagged, and routinely cherry-picked.

Q6: Can the bar coexist with Bartender or iStat Menus?
A: Yes—set Window Level to “Status Bar”. If you choose “Popup” it will overlay third-party icons; pick whichever feels less intrusive.

Q7: Does dwindle work with balance-sizes on already-resized windows?
A: Absolutely. The command treats the binary tree like any other tiling tree.

Closing thought: HyprSpace does not try to be a flashy “ultimate” desktop. It quietly grafts three proven Linux paradigms onto the lightest native tiling manager macOS has ever seen. If your daily routine involves code, browser, and terminal ping-pong, the five-minute install pays for itself within the first hour—and your neck will thank you on an ultrawide.