Skip to content
Overview
Configuration Reference
Scratchpad

Scratchpad

The scratchpad lets you store windows off-screen and bring them back with a keybinding. Think of it as a second desktop that holds windows you want to keep accessible but not always visible.

Keybinding

Add to your config.lua:

-- Toggle scratchpad: SUPER + SHIFT + minus
samwm.bind("SUPER+SHIFT", "minus", "scratchpad", "Toggle scratchpad")

How It Works

  1. Focus a window and press SUPER+SHIFT+minus to send it to the scratchpad
  2. The window is hidden and moved off-screen
  3. Press the same keybinding again to show the scratchpad window
  4. Pressing again hides it back to the scratchpad

If you have multiple scratchpad windows, they cycle through on each toggle.

Scratchpad Window Behavior

  • Scratchpad windows retain their geometry
  • They remember which workspace they came from
  • When shown, they return to the current workspace
  • When hidden back, they go back off-screen

Lua API

Toggle Scratchpad 

samwm.scratchpad("toggle")

List Scratchpad Windows 

local windows = samwm.get_scratchpad()
for _, w in ipairs(windows) do
    print(w.title, w.class)
end

Add Window to Scratchpad 

samwm.scratchpad("add", window_id)

Remove Window from Scratchpad 

samwm.scratchpad("remove", window_id)

Show Scratchpad 

samwm.scratchpad("show")

Hide Scratchpad 

samwm.scratchpad("hide")

Configuration

Scratchpad settings in config.lua:

-- General settings
samwm.general({
    scratchpad = {
        -- Position when shown (relative to screen)
        -- Options: center, left, right, top, bottom
        position = "center",

        -- Floating by default when shown
        floating = true,

        -- Remember geometry per window
        remember_size = true,
    }
})

Event Hooks 

-- When window is sent to scratchpad
samwm.on("scratchpad_add", function(window)
    print("Added to scratchpad:", window.title)
end)

-- When window is shown from scratchpad
samwm.on("scratchpad_show", function(window)
    print("Showing from scratchpad:", window.title)
end)

-- When window is hidden to scratchpad
samwm.on("scratchpad_hide", function(window)
    print("Hiding to scratchpad:", window.title)
end)

Use Cases

  • Terminal on demand: Keep a terminal in scratchpad, bring it up with SUPER+SHIFT+minus
  • Music player: Send your music player to scratchpad, toggle it when needed
  • Notes: Keep a notes app in scratchpad for quick access
  • Reference windows: Keep documentation or reference material available

Example: Scratchpad Terminal 

-- Terminal scratchpad
samwm.bind("SUPER+SHIFT", "Return", "scratchpad_toggle", "Toggle scratchpad terminal")

-- Autostart terminal in scratchpad
samwm.on("startup", function()
    os.execute("foot &")
    -- Give it a moment to open
    os.execute("sleep 0.5")
    -- Send to scratchpad
    samwm.scratchpad("add", samwm.get_focused())
end)

Multiple Scratchpads

You can create multiple scratchpad groups:

-- Group 1: General scratchpad
samwm.bind("SUPER+SHIFT", "minus", "scratchpad group=1", "Toggle scratchpad")

-- Group 2: Special scratchpad
samwm.bind("SUPER+SHIFT", "equal", "scratchpad group=2", "Toggle special scratchpad")
-- Each group operates independently
samwm.scratchpad("add", window_id, "group=2")
samwm.scratchpad("toggle", "group=2")

Tips

  • Use with resize keybindings to adjust scratchpad window size when shown
  • Combine with window rules to auto-send certain apps to scratchpad:
-- Auto-send music player to scratchpad
samwm.windowrule(
    { class = "Spotify" },
    { scratchpad = "true" }
)
LayoutsHot Reload