A I3/Sway like scratchpad extension for AeroSpace WM
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.
demo.mp4
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?
Move the current focused window to the scratchpad workspace.
aerospace-scratchpad move <pattern>
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"
# If you use more than one monitor make sure to assign the `.scratchpad` workspace
# to a non-main monitor for a better UX
[workspace-to-monitor-force-assignment]
".scratchpad" = ['secondary', 'main']
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)\""
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 likeDEBUG
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.