Skip to content
Tsumiki

Overview

What is Tsumiki?

Section titled “What is Tsumiki?”

Tsumiki (formerly Hydepanel) is a modular status bar for the Hyprland Wayland compositor. Built on the Fabric widget system, it provides a flexible architecture for building custom desktop panels through composable widgets.

The name Tsumiki (積み木) is Japanese for “building blocks” — reflecting the project’s modular, stackable design.

Prerequisites

Section titled “Prerequisites”

Before installing Tsumiki, ensure your system meets these requirements:

Requirement Notes
Hyprland A functioning Hyprland installation is required
JetBrains Nerd Font Required for icon and glyph rendering
Python 3.12+ Tsumiki targets Python 3.12
uv Python package manager used to install dependencies (uv sync)
Arch Linux (recommended) Packages optimized for Arch; other distros may need manual setup
NetworkManager Required for network-related widgets and services
PipeWire Required for audio-related widgets and OSD

Key Concepts

Section titled “Key Concepts”

Widgets

Section titled “Widgets”

Widgets are the individual building blocks that appear in the bar. There are 45+ built-in widgets covering:

  • System info — CPU, memory, GPU, storage, network usage
  • Hardware control — Volume, brightness, microphone, battery
  • Desktop management — Workspaces, window title, taskbar
  • Utilities — Screenshot, OCR, clipboard, screen recording
  • Productivity — Pomodoro timer, Kanban board, stopwatch, emoji picker
  • Integration — Weather, media controls, Git companion, DNS switcher

Each widget is configured under [widgets.<name>] in config.toml. See the Widgets Reference for the complete list.

Modules

Section titled “Modules”

Modules are larger UI surfaces that go beyond the bar — they are standalone windows or overlays:

  • Bar — The main panel itself
  • Notification System — Desktop notification display
  • Dock — Application dock with intellihide
  • Overview — Full-screen workspace exposé
  • Launcher — Keyboard-driven application search
  • OSD — On-screen displays for volume, brightness, etc.
  • Desktop Clock — Decorative clock overlay
  • Desktop Quotes — Inspirational quote display

Modules are configured under [modules.<name>] in config.toml. See the Modules Reference for details.

Layout

Section titled “Layout”

Widget placement in the bar is controlled by the [layout] section of config.toml:

[layout]
left_section = ["workspaces", "window_title"]
middle_section = ["date_time"]
right_section = ["volume", "battery", "system_tray"]

Widgets can also be grouped together or placed in collapsible groups. See Configuration for details.

Services

Section titled “Services”

Services are background processes that supply data to widgets — they monitor battery levels, network state, media players, weather, and more. Widgets connect to services via GTK signals, keeping updates efficient.

Architecture

Section titled “Architecture”

Tsumiki’s architecture follows a layered design:

┌──────────────────────────────────────────────┐
│                  main.py                       │
│   ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│   │ Config    │  │ CSS      │  │ Module     │  │
│   │ Loader   │  │ Compiler │  │ Init       │  │
│   └──────────┘  └──────────┘  └───────────┘  │
└─────────────────────┬────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ Services │  │ Widgets  │  │ Modules  │
  │ (DBus    │  │ (Panel   │  │ (Overlay │
  │ polling) │  │ buttons) │  │ windows) │
  └──────────┘  └──────────┘  └──────────┘
  • Services run in the background and emit GTK signals on state changes
  • Widgets are panel buttons that subscribe to service signals
  • Modules are standalone GTK windows for overlays and popups

See the Architecture page for a deeper look.

Section titled “Recommended Path”
  1. Install Tsumiki — Clone, install dependencies, set up the environment.
  2. Follow First Steps — Start the bar, configure your layout, apply post-installation rules.
  3. Learn Configuration — Understand the TOML config structure and available options.
  4. Choose your theme — Start with a built-in theme or create your own with Making Themes.
  5. Explore — Add widgets, enable modules, customize behavior.

Need Help?

Section titled “Need Help?”