home / skills / quantmind-br / skills / hyprscratch-docs

hyprscratch-docs skill

safe

/hyprscratch-docs

This skill helps you manage Hyprland scratchpads with easy configuration, cycling, and daemon options for efficient window management.

npx playbooks add skill quantmind-br/skills --skill hyprscratch-docs

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.3 KB

---
name: hyprscratch-docs
description: |
  Hyprscratch - Scratchpad management utility for Hyprland window manager.
  Use when configuring scratchpads, managing floating windows, setting up Hyprland keybinds for scratchpad toggling, or automating window management.
  Keywords: hyprland, scratchpad, window-management, wayland, rust, nix, home-manager, floating-windows, special-workspace, daemon, keybinds, hyprland-config.
compatibility: Hyprland window manager on Wayland. Install via Cargo, AUR (Arch), or Nix.
metadata:
  source: https://github.com/sashetophizika/hyprscratch
  total_docs: 2
  generated: 2026-02-02T02:45:00Z
---

# Hyprscratch

> Hyprscratch makes scratchpads in Hyprland painless in a well-integrated and flexible way. Supports workspace-local scratchpads, special workspaces, multiple active scratchpads, cycling, event listeners, and extensive configuration options.

## Quick Start

```bash
# In hyprland.conf:

# Start the daemon
exec-once = hyprscratch init clean eager

# Bind scratchpads
bind = $mainMod, b, exec, hyprscratch btop "[size monitor_h*0.7 monitor_h*0.8] alacritty --title btop -e btop" persist pin
bind = $mainMod, f, exec, hyprscratch "Mozilla Firefox" firefox special monitor 1
```

## Installation

```bash
# Cargo (Rust)
cargo install hyprscratch

# Arch Linux (AUR)
paru -S hyprscratch

# Nix (non-NixOS)
nix profile install github:sashetophizika/hyprscratch
```

## Documentation

Documentacao completa em `docs/`. Consulte `docs/000-index.md` para navegacao detalhada.

### By Topic

| Topic | Files | Description |
|-------|-------|-------------|
| Installation | 001 | Nix Flakes, Home Manager setup |
| Configuration & Usage | 002 | Daemon options, scratchpad options, config file |

### By Keyword

| Keyword | File |
|---------|------|
| nix | `docs/001-NIX.md` |
| nix-flakes | `docs/001-NIX.md` |
| home-manager | `docs/001-NIX.md` |
| installation-guide | `docs/001-NIX.md` |
| hyprland | `docs/002-README.md` |
| scratchpad | `docs/002-README.md` |
| window-management | `docs/002-README.md` |
| wayland | `docs/002-README.md` |
| daemon-options | `docs/002-README.md` |
| scratchpad-options | `docs/002-README.md` |
| config-file | `docs/002-README.md` |
| keybinds | `docs/002-README.md` |
| special-workspace | `docs/002-README.md` |
| groups | `docs/002-README.md` |

### Learning Path

1. **Foundation**: Read `docs/001-NIX.md` for Nix-based installation
2. **Core Understanding**: Learn main features from `docs/002-README.md`
3. **Practical Application**: Configure scratchpads and daemon options

## Common Tasks

### Install via Nix/Home Manager
-> `docs/001-NIX.md` (Flake input, Home Manager module, nix profile)

### Initialize the Daemon
-> `docs/002-README.md` (exec-once = hyprscratch init [options])

### Configure Scratchpads in hyprland.conf
-> `docs/002-README.md` (bind syntax with title, command, options)

### Use Dedicated Config File
-> `docs/002-README.md` (~/.config/hypr/hyprscratch.conf format)

### Daemon Options (clean, spotless, eager)
-> `docs/002-README.md` (auto-hide behavior, eager spawn)

### Scratchpad Options (persist, cover, sticky, special)
-> `docs/002-README.md` (extensive list of behavior modifiers)

### Group Multiple Scratchpads
-> `docs/002-README.md` (group syntax in config file)

### Extra Commands (cycle, previous, hide-all)
-> `docs/002-README.md` (subcommands for advanced control)

Overview

This skill helps manage scratchpads for the Hyprland Wayland window manager. It provides a daemon and CLI to define, toggle, and automate floating scratchpads, special workspaces, and related keybinds. Designed for flexible workflow setups, it supports multiple active scratchpads, workspace-local behavior, and rich configuration options.

How this skill works

The tool runs a background daemon and exposes a CLI used from hyprland.conf keybinds or scripts. It listens to Hyprland events and manages scratchpad windows by spawning, hiding, sticking, or moving them to special workspaces. Configuration can live in a dedicated config file or be passed via hyprland keybinds and supports groups, modifiers (persist, cover, sticky), and daemon options (clean, spotless, eager).

When to use it

When you want scratchpads that are local to a workspace or shared across workspaces.
When you need keybinds in hyprland.conf to spawn or toggle floating tools (terminals, system monitors, browsers).
When automating window lifecycle (auto-hide, eager spawn, or persistent scratchpads).
When you want grouped scratchpads or to cycle through multiple scratchpads with a single keybind.
When integrating with Nix or Home Manager for reproducible configuration.

Best practices

Run the daemon via exec-once in hyprland.conf to keep behavior consistent across sessions.
Define scratchpads with clear titles and unique identifiers so the CLI and daemon match windows reliably.
Use persist, sticky, or cover modifiers intentionally—persist keeps state, cover forces z-order behavior, sticky keeps the scratchpad across workspaces.
Place complex group or special-workspace rules in the dedicated config file for maintainability instead of long hyprland.conf bind lines.
Test new scratchpad commands with simple terminal apps before assigning heavyweight applications to avoid spawn delays.

Example use cases

Bind a terminal scratchpad: toggle an alacritty instance sized to 70–80% of the monitor for quick shell access.
Create a system monitor scratchpad (btop) that persists and pins to a monitor for instant monitoring.
Configure a browser as a special workspace scratchpad for fast reference without switching your main workspace layout.
Group multiple developer tools (editor, terminal, REPL) into a single cycle command to rotate through them with one keybind.
Use daemon eager option to spawn frequently used scratchpads at startup to eliminate first-use lag.

FAQ

How do I start the daemon reliably?

Add an exec-once entry in hyprland.conf such as: exec-once = hyprscratch init clean eager. This ensures the daemon launches when Hyprland starts.

Where do I put complex scratchpad rules?

Use the hyprscratch config file (~/.config/hypr/hyprscratch.conf) to declare groups, special workspaces, and persistent options for easier maintenance and reuse.