Niri Scratchpad 2.0

No config files required.

You must define a static workspace named stash in your Niri configuration.
All stashed scratchpads are moved here.

workspace "stash" { }

---

Static Scratchpads

Static scratchpads show and hide windows based on properties such as appid or title.
If multiple windows match, all matches are selected. If any matched window is in stash all windows will be shown on your focused workspace.

No background process is required when using only static scratchpads.

Example Niri bindings

Toggle Firefox by app id:

binds {
    Mod+F { spawn "niri-scratchpad" "target" "appid" "firefox"; }
}

Toggle by window title:

binds {
    Mod+S { spawn "niri-scratchpad" "target" "title" "Spotify"; }
}

Spawn if not running:

binds {
    Mod+Return {
        spawn "niri-scratchpad" "target" "--spawn" "alacritty" "appid" "alacritty" ;
    }
}

One note, is while --as-float is technically available with the spawn command, initial spawn cannot inherit the floating behavior. I suggest setting this through niri window rules if you want that behavior. Similar to auto startup if you want that

---

Dynamic Scratchpads

Dynamic scratchpads assign a window to a numbered register.
You can toggle the window with a keybind using that register. Associations between registers and their windows do not persist after session end.

Example Niri bindings

Create / toggle register 1:

binds {
    Mod+Q { spawn "niri-scratchpad" "create" "1"; }
}

Delete register 1:

binds {
    Mod+Ctrl+Q { spawn "niri-scratchpad" "delete" "1"; }
}

Create as floating:

binds {
    Mod+Shift+Q { spawn "niri-scratchpad" "create" "1" "--as-float"; }
}

---

Command Interface

Static Targeting

Command	Description
target appid <app_id>	Match window(s) by app id
target title <window_title>	Match window(s) by title

Options

Option	Description
--spawn <command>	Spawn application if no window matches
--as-float	Set matched windows to floating

---

Dynamic Registers

Command	Description
create <number>	Create or toggle scratchpad
delete <number>	Remove scratchpad and restore window
get <number>	Query scratchpad information
daemon	Start background daemon

Options

Option	Description
-o, --output [title|appid]	Print selected property to stdout
--as-float	Set window to floating when registering

---

Installation

This is a single Rust binary.

Prebuilt x86_64 binaries are provided.
Download, place in your PATH, and make executable:

chmod +x niri-scratchpad

---

Building

Dependencies:

• rust
• cargo
• niri-ipc
• serde
• clap

Build:

cargo build --release

---

Nix (Flakes)

Add to inputs:

inputs {
  niri-scratchpad.url = "github:argosnothing/niri-scratchpad";
}

Add to system packages:

environment.systemPackages = [
  inputs.niri-scratchpad.packages.${pkgs.system}.default
];

---

Related Resources

• Static scratchpads via spawn command:
  https://github.com/gvolpe/niri-scratchpad

• Niri scratchpad discussion:
  niri-wm/niri#329

---

Hidden Workspace Experimental Branch

Experimental branch:

https://github.com/argosnothing/niri-scratchpad-rs/tree/hidden-workspaces

Draft Niri PR:

niri-wm/niri#2997

This approach hides the stash workspace while maintaining full scratchpad functionality.

To use:

• set hidden true on the stash workspace
• use niri msg workspaces-with-hidden instead of workspaces

Hidden workspaces are not advertised to the event stream, so bars and workspace widgets remain unaffected.

Feedback is welcome if you try this branch.