AeroSpork is an i3-like tiling window manager for macOS

300

Have an automation, integration, or workflow worth sharing? Open an issue or pull request to add it to this list. The source of this page is in the ./docs directory.

1. Move windows by dragging any part of the window

defaults write -g NSWindowShouldDragOnGesture -bool true

Windows can then be moved by holding ctrl + cmd and dragging any part of the window, not only the title bar.

2. Highlight focused windows with colored borders

JankyBorders draws a colored border around the focused window.

after-startup-command can start it together with AeroSpork:

after-startup-command = [
    # JankyBorders has a built-in detection of already running process,
    # so it won't be run twice on AeroSpork restart
    'exec-and-forget borders active_color=0xffe1e3e4 inactive_color=0xff494d64 width=5.0'
]

3. Raycast extension

A third party Raycast extension exists for upstream AeroSpace: https://www.raycast.com/limonkufu/aerospace

It drives the aerospace binary, so the command name has to be changed to aerospork to work here. It lets you search for commands by name instead of recalling their shortcuts.

4. Disable windows opening animations

Observable in Google Chrome

defaults write -g NSAutomaticWindowAnimationsEnabled -bool false

5. Use trackpad gestures to switch workspaces

These commands focus the next or previous workspace on the monitor the mouse is on:

aerospork workspace "$(aerospork list-workspaces --monitor mouse --visible)" && aerospork workspace next

aerospork workspace "$(aerospork list-workspaces --monitor mouse --visible)" && aerospork workspace prev

Use the software of your choice to assign trackpad gestures to the respective commands. A few third party options, in alphabetical order. All of them were written for upstream AeroSpace, so they invoke the aerospace binary and read AEROSPACE_* environment variables; both need adjusting for AeroSpork:

Caution
Make sure you trust the project authors before running a distributed binary. Otherwise, inspect the source and build it yourself.

6. Show AeroSpork workspaces in Sketchybar

AeroSpork workspace indicators can be driven from Sketchybar. Use these snippets as a starting point.

~/.aerospork.toml
# Run Sketchybar together with AeroSpork
# sketchbar has a built-in detection of already running process,
# so it won't be run twice on AeroSpork restart
after-startup-command = ['exec-and-forget sketchybar']

# Notify Sketchybar about workspace change
on-focused-workspace-changed = ['exec-and-forget sketchybar --trigger aerospork_workspace_change FOCUSED_WORKSPACE=$AEROSPORK_FOCUSED_WORKSPACE']
~/.config/sketchybar/sketchybarrc
sketchybar --add event aerospork_workspace_change

for sid in $(aerospork list-workspaces --all); do
    sketchybar --add item space.$sid left \
        --subscribe space.$sid aerospork_workspace_change \
        --set space.$sid \
        background.color=0x44ffffff \
        background.corner_radius=5 \
        background.height=20 \
        background.drawing=off \
        label="$sid" \
        click_script="aerospork workspace $sid" \
        script="$CONFIG_DIR/plugins/aerospork.sh $sid"
done
~/.config/sketchybar/plugins/aerospork.sh
#!/usr/bin/env bash

# make sure it's executable with:
# chmod +x ~/.config/sketchybar/plugins/aerospork.sh

if [ "$1" = "$FOCUSED_WORKSPACE" ]; then
    sketchybar --set $NAME background.drawing=on
else
    sketchybar --set $NAME background.drawing=off
fi

7. Open a new window with AppleScript

exec-and-forget open -a Safari does not open a new window. It brings into focus whichever workspace already contains a Safari window.

To open a new window of a program that supports multiple windows (Safari, Terminal.app), inline an AppleScript in aerospork.toml:

  • Safari

    [mode.main.binding]
    ctrl-g = '''exec-and-forget osascript -e '
    tell application "Safari"
        make new document at end of documents
        activate
    end tell'
    '''
  • Terminal

    [mode.main.binding]
    ctrl-g = '''exec-and-forget osascript -e '
    tell application "Terminal"
        do script
        activate
    end tell'
    '''

8. Disable the "hide application" shortcut

If automatically-unhide-macos-hidden-apps isn’t enough, disable cmd-h altogether. The hotkey then becomes unavailable to apps that use it for something else.

~/.aerospork.toml
[mode.main.binding]
    cmd-h = [] # Disable "hide application"
    cmd-alt-h = [] # Disable "hide others"

9. Take a screenshot to the clipboard with a keyboard shortcut

Bind a shortcut to screencapture, a built-in macOS command.

~/.aerospork.toml
[mode.main.binding]
alt-shift-s = 'exec-and-forget screencapture -i -c'

10. i3-like config

# Reference: https://github.com/i3/i3/blob/next/etc/config

# i3 doesn't have "normalizations" feature that why we disable them here.
# But the feature is very helpful.
# Normalizations eliminate all sorts of weird tree configurations that don't make sense.
# Give normalizations a chance and enable them back.
enable-normalization-flatten-containers = false
enable-normalization-opposite-orientation-for-nested-containers = false

# Mouse follows focus when focused monitor changes
on-focused-monitor-changed = ['move-mouse monitor-lazy-center']

[mode.main.binding]
    # See: https://github.com/wbsmolen/aerospork/blob/main/docs/goodies.adoc#open-a-new-window-with-applescript
    alt-enter = '''exec-and-forget osascript -e '
    tell application "Terminal"
        do script
        activate
    end tell'
    '''

    # i3 wraps focus by default
    alt-j =         'focus --boundaries-action wrap-around-the-workspace left'
    alt-k =         'focus --boundaries-action wrap-around-the-workspace down'
    alt-l =         'focus --boundaries-action wrap-around-the-workspace up'
    alt-semicolon = 'focus --boundaries-action wrap-around-the-workspace right'

    alt-shift-j = 'move left'
    alt-shift-k = 'move down'
    alt-shift-l = 'move up'
    alt-shift-semicolon = 'move right'

    # Consider using 'join-with' command as a 'split' replacement if you want to enable
    # normalizations
    alt-h = 'split horizontal'
    alt-v = 'split vertical'

    alt-f = 'fullscreen'

    alt-s = 'layout v_accordion' # 'layout stacking' in i3
    alt-w = 'layout h_accordion' # 'layout tabbed' in i3
    alt-e = 'layout tiles horizontal vertical' # 'layout toggle split' in i3

    alt-shift-space = 'layout floating tiling' # 'floating toggle' in i3

    # Not supported, because this command is redundant in AeroSpork mental model.
    # See: https://github.com/wbsmolen/aerospork/blob/main/docs/guide.adoc#floating-windows
    #alt-space = 'focus toggle_tiling_floating'

    # `focus parent`/`focus child` are not yet supported, and it's not clear whether they
    # should be supported at all https://github.com/wbsmolen/aerospork/issues/5
    # alt-a = 'focus parent'

    alt-1 = 'workspace 1'
    alt-2 = 'workspace 2'
    alt-3 = 'workspace 3'
    alt-4 = 'workspace 4'
    alt-5 = 'workspace 5'
    alt-6 = 'workspace 6'
    alt-7 = 'workspace 7'
    alt-8 = 'workspace 8'
    alt-9 = 'workspace 9'
    alt-0 = 'workspace 10'

    alt-shift-1 = 'move-node-to-workspace 1'
    alt-shift-2 = 'move-node-to-workspace 2'
    alt-shift-3 = 'move-node-to-workspace 3'
    alt-shift-4 = 'move-node-to-workspace 4'
    alt-shift-5 = 'move-node-to-workspace 5'
    alt-shift-6 = 'move-node-to-workspace 6'
    alt-shift-7 = 'move-node-to-workspace 7'
    alt-shift-8 = 'move-node-to-workspace 8'
    alt-shift-9 = 'move-node-to-workspace 9'
    alt-shift-0 = 'move-node-to-workspace 10'

    alt-shift-c = 'reload-config'

    alt-r = 'mode resize'

[mode.resize.binding]
    h = 'resize width -50'
    j = 'resize height +50'
    k = 'resize height -50'
    l = 'resize width +50'
    enter = 'mode main'
    esc = 'mode main'

Use these to write an on-window-detected callback.

Application name Application ID

1Password

com.1password.1password

Activity Monitor

com.apple.ActivityMonitor

AirPort Utility

com.apple.airport.airportutility

Alacritty

org.alacritty

Android Studio

com.google.android.studio

App Store

com.apple.AppStore

AppCode

com.jetbrains.AppCode

Arc Browser

company.thebrowser.Browser

Audio MIDI Setup

com.apple.audio.AudioMIDISetup

Automator

com.apple.Automator

Battle.net

net.battle.app

Books

com.apple.iBooksX

Brave

com.brave.Browser

Calculator

com.apple.calculator

Calendar

com.apple.iCal

Chess

com.apple.Chess

CLion

com.jetbrains.CLion

Clock

com.apple.clock

ColorSync Utility

com.apple.ColorSyncUtility

Console

com.apple.Console

Contacts

com.apple.AddressBook

Dictionary

com.apple.Dictionary

Disk Utility

com.apple.DiskUtility

Docker

com.docker.docker

FaceTime

com.apple.FaceTime

Figma

com.figma.Desktop

Find My

com.apple.findmy

Finder

com.apple.finder

Firefox

org.mozilla.firefox

Freeform

com.apple.freeform

Ghostty

com.mitchellh.ghostty

GIMP

org.gimp.gimp-2.10

Google Chrome

com.google.Chrome

Grapher

com.apple.grapher

Home

com.apple.Home

iMovie

com.apple.iMovieApp

Inkscape

org.inkscape.Inkscape

IntelliJ IDEA Community

com.jetbrains.intellij.ce

IntelliJ IDEA Ultimate

com.jetbrains.intellij

iTerm2

com.googlecode.iterm2

Karabiner-Elements

org.pqrs.Karabiner-Elements.Settings

kdenlive

org.kde.Kdenlive

Keychain Access

com.apple.keychainaccess

Keynote

com.apple.iWork.Keynote

Kitty

net.kovidgoyal.kitty

Mail

com.apple.mail

Maps

com.apple.Maps

Marta

org.yanex.marta

Messages

com.apple.MobileSMS

Music

com.apple.Music

Notes

com.apple.Notes

Obsidian

md.obsidian

Pages

com.apple.iWork.Pages

Photo Booth

com.apple.PhotoBooth

Photos

com.apple.Photos

Podcasts

com.apple.podcasts

Preview

com.apple.Preview

PyCharm Community

com.jetbrains.pycharm.ce

PyCharm Professional

com.jetbrains.pycharm

QuickTime Player

com.apple.QuickTimePlayerX

Reminders

com.apple.reminders

Safari

com.apple.Safari

Shortcuts

com.apple.shortcuts

Slack

com.tinyspeck.slackmacgap

Spotify

com.spotify.client

Steam

com.valvesoftware.steam

Stocks

com.apple.stocks

Sublime Merge

com.sublimemerge

Sublime Text

com.sublimetext.4

System Settings

com.apple.systempreferences

Telegram

com.tdesktop.Telegram

Terminal

com.apple.Terminal

TextEdit

com.apple.TextEdit

Thunderbird

org.mozilla.thunderbird

Time Machine

com.apple.backup.launcher

Todoist

com.todoist.mac.Todoist

Tor Browser

org.torproject.torbrowser

Transmission

org.m0k.transmission

TV

com.apple.TV

Visual Studio Code

com.microsoft.VSCode

VLC

org.videolan.vlc

VoiceMemos

com.apple.VoiceMemos

VoiceOver Utility

com.apple.VoiceOverUtility

Weather

com.apple.weather

WezTerm

com.github.wez.wezterm

Xcode

com.apple.dt.Xcode

Zen Browser

app.zen-browser.zen