A I3/Sway like scratchpad extension for AeroSpace WM

• Demo
• Basic Usage
• Advanced Usage
• Installation
• How does it work?
• Troubleshooting
• License

Beta: I use this daily, I'll try my best but there might be breaking changes till the 1.0.0 release.

Please report any issues or ideas in the issues section.

From I3 User Guide:

6.21. Scratchpad

There are two commands to use any existing window as scratchpad window. move scratchpad will move a window to the scratchpad workspace. This will make it invisible until you show it again. There is no way to open that workspace. Instead, when using scratchpad show, the window will be shown again, as a floating window, centered on your current workspace (using scratchpad show on a visible scratchpad window will make it hidden again, so you can have a keybinding to toggle). Note that this is just a normal floating window, so if you want to "remove it from scratchpad", you can simple make it tiling again (floating toggle).

As the name indicates, this is useful for having a window with your favorite editor always at hand. However, you can also use this for other permanently running applications which you don’t want to see all the time: Your music player, alsamixer, maybe even your mail client…?

What Are Scratchpads and WHY Are They Good?

The origin of this project

Summon or move a window from the scratchpad workspace to the current workspace.

aerospace-scratchpad show <pattern>

To find the correct pattern run aerospace list-windows --all --json | grep app-name

# ~/.config/aerospace/config.toml
[mode.main.binding] 
# This toggle the scratchpad window show/hide
cmd-ctrl-1 = "exec-and-forget aerospace-scratchpad show Finder"

# Or using summon instead
cmd-ctrl-2 = """
exec-and-forget aerospace-scratchpad summon Finder || \
                aerospace-scratchpad move Finder
"""

# Bring windows one by one to current workspace
ctrl-minus = "exec-and-forget aerospace-scratchpad next"

# A terminal scratchpad a la Guake
ctrl-cmd-t = """
exec-and-forget aerospace-scratchpad show alacritty -F window-title='terminal-scratchpad' \
             || alacritty -t 'terminal-scratchpad'
"""

In order to have a better experience with scratchpads on multi-monitor setups it is recommended to assign the .scratchpad workspace to your main monitor so it won't get focused when hiding/showing scratchpad windows.

See the AeroSpace documentation for more details around the multi-monitor model followed by AeroSpace.

# ~/.config/aerospace/config.toml
# ...your configuration
[workspace-to-monitor-force-assignment]
".scratchpad" = "main"

When using an external launcher or when clicking on a notification if the app related to that notification is in the scratchpad it will inevitably takes focus, which is a bit of an UX inconvenience, I'm experimenting with some solutions. Once I feel it is stable enough I'll merge it to master

Relates to:

• cristianoliveira#53
• cristianoliveira#67

There is a on going issue related to 2 monitors (main/second), upon hiding an app from second monitor, assuming the .scratchpad is on the main, some apps when moved take with them the focus, and the .scratchpad workspace ended up focused on the other monitor. Similar I'm experimenting with a solution, basically move the window to main monitor before hidding it. Once I feel it's stable I merge it.

See more in documentation

By pairing with aerospace-marks you can turn any window into a scratchpad window and bind a toggle key on the fly!

# ~/.config/aerospace/config.toml
[mode.main.binding]
# Mark current window with sp-1 so you can use the shortcut
cmd-shit-ctrl-1 = [
    "exec-and-forget aerospace-marks mark sp-1"
]

# Toggle show/hide the window marked as 'sp-1' as scratchpad window
# If window is not marked does nothing
cmd-ctrl-1 = "exec-and-forget aerospace-scratchpad show \"$(aerospace-marks get sp-1 -a)\""

# Making a mark more specific
ctrl-cmd-t = """
exec-and-forget aerospace-scratchpad show \
               "$(aerospace-marks get term -a)" \
               -F window-title="$(aerospace-marks get term -t)"
"""

Min AeroSpace version: 0.15.x

If you have Homebrew installed, you can install aerospace-scratchpad using the following command:

brew install cristianoliveira/tap/aerospace-scratchpad

If you have Nix installed, you can build and install aerospace-scratchpad using the following command:

nix profile install github:cristianoliveira/aerospace-scratchpad

You can also run without installing it by using:

nix run github:cristianoliveira/aerospace-scratchpad

This will build the default package defined in flake.nix.

If you have Go installed, you can install aerospace-scratchpad directly using:

go install github.com/cristianoliveira/aerospace-scratchpad@latest

This will download and install the latest version of aerospace-scratchpad to your $GOPATH/bin.

After installing, start by checking compatibility and updating Aerospace accordingly:

aerospace-scratchpad info

Next, you may need to include aerospace-scratchpad in the Aerospace context.

To check where the binary is installed, run:

echo $(which aerospace-scratchpad) | sed 's/\/aerospace-scratchpad//g'

Then, in your configuration file, add:

[exec]
    inherit-env-vars = true
# OR
[exec.env-vars]
    # Replace 'aerospace-scratchpad/install/path' with the actual path from the command above
    PATH = 'aerospace-scratchpad/install/path/bin:${PATH}'

This extension uses Inter-Process Communication (IPC), specifically through a Unix socket, to communicate directly with the AeroSpace service, just like the built-in AeroSpace CLI. By avoiding repeated process spawning, this approach offers lower latency and better efficiency, especially when one has to query AeroSpace many times.

See: https://github.com/cristianoliveira/aerospace-ipc

This CLI runs about 3x faster than a bash script that does the same.

# time aerospace-scratchpad show Finder
# aerospace-scratchpad show Finder  0.01s user 0.01s system 12% cpu 0.125 total
# aerospace-scratchpad show Finder  0.01s user 0.01s system 14% cpu 0.097 total
# aerospace-scratchpad show Finder  0.01s user 0.01s system 12% cpu 0.140 total

# time bash scripts/scratchpad.sh Finder
# scripts/benchmark.sh Finder  0.13s user 0.08s system 75% cpu 0.281 total
# scripts/benchmark.sh Finder  0.14s user 0.09s system 82% cpu 0.276 total
# scripts/benchmark.sh Finder  0.14s user 0.09s system 80% cpu 0.289 total

See: scripts/benchmarks.sh for details, and test it yourself.

If you encounter issues with aerospace-scratchpad, you can use the following environment variables to help diagnose and resolve problems:

• AEROSPACE_SCRATCHPAD_LOGS_PATH: Set this environment variable to specify the path for the AeroSpace scratchpad logs. By default, logs are stored at /tmp/aerospace-scratchpad.log.

• AEROSPACE_SCRATCHPAD_LOGS_LEVEL: Use this environment variable to set the logging level for the AeroSpace scratchpad. The default level is DISABLED. You can set it to other levels like DEBUG to get more detailed logs.

These environment variables can be set directly in the AeroSpace configuration file to ensure they are available whenever AeroSpace is running. Add the following to your AeroSpace config

[exec.env-vars]
    AEROSPACE_SCRATCHPAD_LOGS_PATH = "/path/to/your/logfile.log"
    AEROSPACE_SCRATCHPAD_LOGS_LEVEL = "DEBUG"

Alternatively, you can export these environment variables in your shell configuration file (e.g., .bashrc, .zshrc):

  export AEROSPACE_SCRATCHPAD_LOGS_LEVEL="DEBUG"
  export AEROSPACE_SCRATCHPAD_LOGS_PATH="/path/to/your/logfile.log"

Replace the paths and values with your desired settings.

This project is licensed under the terms of the LICENSE file.