hakuspace

Haku Space

Wayland dotfiles and desktop shell for Hyprland / Niri / MangoWM / Labwc

Classic (Waybar / Rofi / SwayNC) + Hikai (Quickshell-native desktop experience)

Haku (ハク) is the very highest Value, the manifestation of a wish. It means "the shape of a soul," "that which is irreplaceable." - Made in Abyss -

Welcome to Haku Space

Hikai - Installation - Update - Packages - Keybinding - Troubleshooting - Docs - Contributing - Credits

Need help or want to chat? Join our Discord server or follow us on TikTok for showcase videos!

• Dual Shell Modes: Keep the proven Classic stack (Waybar / Rofi / SwayNC) or switch to Hikai, the native Quickshell desktop shell.
• Multi-WM Support: Hyprland, Niri, MangoWM, and Labwc share the same HakuSpace scripts, state, themes, and user customization layer.
• Arch Linux Focused: Currently developed and tested exclusively on Arch Linux (legacy guides for NixOS and Fedora are kept for reference, but are not actively tested).
• Modular Management: Install, update, link, unlink, diagnose, and roll back individual modules safely.
• Extensible: Highly customizable via ~/hakucfg without touching the main repo files.
• See Guide for: Arch Linux | NixOS (Outdated) | Fedora (Outdated)

---

Shell Modes

Haku Space provides two interchangeable desktop shells. Your chosen mode is saved automatically and restored on your next login.

Hikai - Quickshell Native

Hikai is HakuSpace's Quickshell-based desktop shell, with a shared settings, state and service layer. It integrates the bar, menus, notifications and desktop surfaces into a coordinated UI. See Hikai architecture for the technical contracts.

[!note] Access Hikai:

Classic - Waybar / Rofi / SwayNC

Classic keeps the original Haku Space experience: Waybar, Rofi menus, SwayNC, and the script-driven workflow. You can switch between Hikai and Classic anytime:

~/.local/bin/haku_backend.sh set hikai
~/.local/bin/haku_backend.sh set classic
~/.local/bin/haku_backend.sh --toggle
~/.local/bin/haku_backend.sh --verify

You can also press SUPER + ESCAPE at any time as an emergency shortcut to switch back to Classic.

Hikai highlights

• Shell controls: Top bar, taskbar/dock, HakuMenu, launcher, dashboard, notifications and sidebar coordinated by Quickshell.
• Window navigation: Quick switcher and overview, with compositor-dependent capabilities.
• System monitoring: Full Task Manager and a compact HakuMenu view for CPU, memory, processes and other supported metrics.
• Wallpapers: Image and video browsing, folder categories and video-quality preferences. Hikai uses awww for static images and a separate native QtMultimedia renderer for video; Classic uses awww / mpvpaper.
• Images and screenshots: A shared image editor for crop, rotation, annotations and export, including avatar and screenshot workflows.
• Session controls: Native Hikai lock screen and idle policy, with explicit recovery/fallback integration. Classic retains its existing external tools.
• Personalization: Light/dark appearance, accent sync, settings search and configuration through ~/hakucfg.

Feature availability and keybindings can vary by compositor. Hikai does not replace the window manager, application dialogs or the XDG desktop portal for other applications.

---

Key Features

• User Configuration (~/hakucfg): Stores your personal configs separately from the base files.
• Accent Colors: Synced across configured applications and icon themes.
• Smart Accent Color: Automatically generates the accent color based on your current wallpaper.
• Flexible Waybar Layouts: Supports 7 styles in Classic mode: top, left, coredge, minimal, neon, island, legacy, tokyo.
• Wallpaper Automation: Classic uses awww / mpvpaper; Hikai has its own wallpaper browsing and native video-rendering path, with playback and quality settings.
• Taskbar: Classic provides a secondary Waybar taskbar; Hikai integrates its taskbar and dock into the Quickshell UI.
• Haku Space Classic Mini-Apps:
  • Unique Cava Underbar: Built-in, dynamic audio visualizer waves seamlessly layered beneath your bar.
  • Desktop Icons: Built-in, items in ~/Desktop are rendered directly on your desktop with drag-and-drop support.
  • Rounded Screen Corners: Built-in, smooth rounded corners and frame around your screen.
  • Edge Trigger: Built-in, hover your mouse at the screen edges to quickly pop up menus or panels.

[!note] HakuSpace is modular, but background resource usage depends on which shell services, media decoders and features are active. Use measurements from your own session rather than assuming all inactive features cost nothing.

[!tip] See the measurement guidance in the Performance section below.

---

Programs

See more information in: pkg-core | pkg-service | pkg-optional

Specific packages for each WM: pkg-hyprland | pkg-niri | pkg-mango | pkg-labwc

Component	Programs
Shell Runtime	Quickshell
Classic Tools	Waybar, Rofi, SwayNC
Terminal	Kitty
Shell	Fish + Starship
File Manager	Thunar
Wallpaper	Hikai: Awww for images + native QtMultimedia video renderer; Classic: Awww + mpvpaper
Idle Management	Hikai: native idle policy; Classic: Hypridle
Screen Lock	Hikai: native Quickshell session lock with hyprlock fallback; Classic: Hyprlock
Screen Recording	wl-screenrec
Editor	VS Code (replaceable)
Browser	Firefox (replaceable)
Display Manager (Default)	Ly

XDG Desktop Portal: GTK by default, but each WM will use its specific, recommended portal according to its official wiki (Hyprland uses Hyprland, Niri uses GNOME, and MangoWM/Labwc use wlr).

Accent Color based on wallpaper using python-colorthief.

---

Installation Guide

[!warning] Notice for Fedora & NixOS users: Development and testing focus on Arch Linux. The Fedora and NixOS setups are legacy and unsupported. See the retained Fedora Guide and NixOS notes for reference.

Prerequisites

• You have completed the installation of Arch Linux (or a derivative distribution).
• You have installed and configured essential utilities such as Wi-Fi, Bluetooth, Audio, and the necessary hardware drivers.
• You are comfortable reading configuration files and scripts to customize this dotfiles project.

Clone Haku Space

Stable release (recommended):

cd ~
git clone --depth 1 --branch v26.11 https://github.com/hakuimaku/hakuspace.git ~/hakuspace
cd ~/hakuspace

If you prefer the latest development changes:

cd ~
git clone https://github.com/hakuimaku/hakuspace.git ~/hakuspace
cd ~/hakuspace

Method 1 - Automatic Installation (install.sh)

This is the recommended method for a complete Haku Space setup. The installer lets you select your Window Manager and deployment mode, then orchestrates the package, config, core-script, state, asset, shell, display-manager, desktop-default, and diagnostic modules for you.

cd ~/hakuspace
chmod +x install.sh
./install.sh

After the installer finishes, restart your computer and log in to Hyprland, Niri, MangoWM, or Labwc.

Method 2 - Manual / Modular Installation

Use this method if you want full control over which package groups and configuration modules are installed. You can inspect the available targets first:

cd ~/hakuspace
./packages.sh --list
./link.sh --list

Full Haku Space, module by module

The example below installs Niri. Replace niri with hyprland, mango, or labwc as needed. You can also pass more than one WM group/module.

cd ~/hakuspace

# 1. Bootstrap/check the installer dependencies (Arch/yay flow)
./scripts/dependencies.sh

# 2. Review and install package groups
./packages.sh --plan core service optional niri
./packages.sh core service optional niri

# 3. Create the base directories
./scripts/directories.sh

# 4. Install configs that are intentionally copied only once
./scripts/once_configs.sh

# 5. Deploy common configs + core scripts + your WM config
./link.sh --all niri

# 6. Optional: install visual software and wallpapers independently
./scripts/setup.sh setup
./scripts/assets.sh

# 7. Initialize Haku Space state and user overrides
./scripts/state.sh init
./scripts/hakucfg.sh sync

# 8. Optional system integration used by the full installer
./scripts/shell_setup.sh
./scripts/display_manager.sh
./scripts/desktop_defaults.sh

# 9. Verify the installation
./doctor.sh

./link.sh --all deploys all registered common configs and the scripts from src/core into ~/.local/bin. If you want an even smaller setup, link only the modules you need instead, for example:

./link.sh quickshell kitty core niri

[!note] optional, assets, shell setup, display-manager setup, and desktop defaults are not required for every manual installation. Skip the modules you do not want.

Quickshell only - Hikai mode

If you already have a supported Wayland compositor configured and only want the Haku Space Quickshell / Hikai interface, you do not need to deploy all Haku Space configs or replace your WM configuration.

cd ~/hakuspace

# 1. Install the core package group.
#    Quickshell is expected to be included in pkg-core.txt.
./scripts/dependencies.sh
./packages.sh --plan core
./packages.sh core

# 2. Create base directories and deploy only Quickshell + Haku Space core scripts
./scripts/directories.sh
./link.sh quickshell core

# 3. Initialize the state/config data used by Hikai
./scripts/state.sh init
./scripts/hakucfg.sh sync

# 4. Start Hikai now and verify it
~/.local/bin/haku_backend.sh set hikai
~/.local/bin/haku_backend.sh --verify

If you keep your own WM configuration instead of linking a Haku Space WM module, add this command to your compositor's autostart so the selected Hikai backend starts again on future sessions:

~/.local/bin/session_start.sh --early

Haku Space's bundled Hyprland, Niri, MangoWM, and Labwc configs already call this startup hook, so no extra step is needed when you use those configs.

[!important] Hikai depends on the scripts deployed by the core module. Linking only quickshell is not enough for the full Haku Space Hikai experience.

After Installation

1. Check your appearance

   • Install visual assets with ./scripts/setup.sh setup if you skipped this during installation.
   • Installation and activation are separate: a GTK/icon theme may be installed without becoming the selected theme.
   • Inspect with ./scripts/setup.sh status and choose/activate a managed theme when desired. Existing third-party selections are preserved unless you confirm a change.

2. Install waybar-cava if you use the Classic Waybar cava module

   yay -S waybar-cava
   

3. Allow the local root user to access X/Xwayland display when needed

   xhost +si:localuser:root
   

   This allows local root GUI applications such as GParted to connect to the current user's X/Xwayland display.

---

Dotfiles Management

Haku Space manages your dotfiles safely without needing Stow or Git worktrees:

• Deployment Modes: Choose between Deep Symlink (default - links individual files so edits sync immediately while keeping ~/.config folders real) or Copy mode.
• Install-only configs: Apps like Thunar, btop, and cava rewrite their own configs, so Haku Space copies them only once on install and never overwrites them on update.
• Safe Customization: ~/hakucfg is preserved by default. Missing templates are seeded, and version-mismatched setting.sh is only replaced after confirmation.

See the full breakdown in: Management & Deployment

Available Commands

Command	Description
./install.sh	Full automatic installation profile
./update.sh	Full automatic update profile
./link.sh [modules]	Link specific modules (e.g. ./link.sh quickshell niri core) or ./link.sh --all
./unlink.sh [modules]	Safely remove tracked symlinks without touching user data (./unlink.sh --all)
./packages.sh [groups]	Install package groups (e.g. ./packages.sh core niri) or ./packages.sh --all
./doctor.sh	Read-only integrity check and troubleshooting instructions
./rollback.sh	Restore previous configuration backups safely

Update Haku Space

Run the updater to fetch dotfiles, deploy selected modules, apply versioned migrations, synchronize state, and run diagnostics. It preserves personal settings in ~/hakucfg unless a documented migration requires a safe transformation. The updater checks visual assets and may offer to repair missing components; it does not routinely refresh already-installed GTK/icon/cursor sources. Explicit refreshes use ./scripts/setup.sh update.

cd ~/hakuspace
./update.sh

For the v26.11 upgrade, check migration status after the update:

./scripts/migrate.sh --status
./scripts/migrate.sh --audit
./doctor.sh

A failed or partial update is not a successful migration. Review the reported backup path and logs under log/ before retrying; do not delete your existing ~/hakucfg data to force a retry.

Rollback & Uninstall Haku Space

If an update breaks something, or you want to restore your previous configs from ~/.backup/:

cd ~/hakuspace
./rollback.sh

If you installed in Symlink mode and want to cleanly remove Haku Space symlinks without deleting your real files:

./unlink.sh --all niri   # Replace with the WM(s) you installed: hyprland niri mango labwc

[!important] Do not manually delete everything in ~/.local/bin or wipe entire ~/.config folders! Read the full step-by-step Uninstall Guide in docs/management.md to safely clean up runtime state, optional assets, and Copy-mode files.

---

Visual Ecosystem

HakuSpace installs its visual suite using scripts/setup.sh. Source downloads are temporary and removed after installation; installed assets remain available:

• Haku Cursor (default: Haku-Dark, size 24)
• Hikaide GTK (default: Hikaide)
• Hikaide-Symbols (automatically recolored to match your active wallpaper/theme accent color!)

Hikai's saved color mode selects Hikaide / Hikaide-Light and Hikaide-Symbols / Hikaide-Symbols-Light only while that managed family is selected. Third-party GTK and icon themes stay unchanged. Icon accent sync is disabled whenever the active icon theme is outside the Hikaide-Symbols family.

hakuspace-archive supplies wallpapers only through ./scripts/assets.sh. The visual projects have independent development and update lifecycles. update.sh updates HakuSpace dotfiles without pulling, rebuilding or installing GTK themes, icons or cursors. The following commands are optional tools for installing visual assets or working with explicitly configured development sources separately:

./scripts/setup.sh status
./scripts/setup.sh update
./scripts/setup.sh apply symbols
./scripts/setup.sh workspace  # Development only: configure retained source paths first

You can also control your accent color and check your visual setup from the terminal:

~/.local/bin/theme_ctl.sh set-accent '#AC7994'
~/.local/bin/theme_ctl.sh apply
~/.local/bin/appearance_ctl.sh status

To see how the internal icon recoloring engine (haku_icon_accent.py) and theme controllers work under the hood, check out Theming Engine & Visual Ecosystem.

---

Performance

The figures below are Classic-stack measurements from a system with 16GB RAM, kept as a rough reference:

• Fresh Arch Linux + Dotfiles (Base): ~1.1 GB RAM
• Taskbar enabled: +77 MB
• Desktop Icons enabled: +100 MB
• Cava Underbar enabled: +100 MB (High CPU usage)
• Rounded Screen enabled: +70 MB
• Edge Trigger enabled: +60 MB

Total: If you use all the built-in mini-apps simultaneously, it will consume at least ~1.5 GB RAM upon startup.

With Hikai (Quickshell) mode, RAM usage is extremely high, making it unsuitable for low-end machines. With Fresh Arch Linux + Dotfiles (Base) + Hikai, RAM usage is more than ~1.7GB. However, it is more streamlined because Cava Underbar, Rounded Screen, Edge Trigger, and Taskbar are already integrated into Hikai, eliminating the need to run additional mini-apps.

[!note] During your actual workflow, RAM consumption will naturally expand further depending on the applications you use and your specific needs.

---

NixOS Configuration

[!warning] NixOS integration is currently legacy and unsupported. The retained scripts/nixos.sh / nix/ implementation is kept for reference, but the current Arch-focused automatic installer does not provide a working NixOS installation path.

See NixOS Integration for the retained legacy design.

---

Keybinding

• See more keybinding in: Hyprland | Niri | MangoWM | Labwc
• Common Hotkeys:

Bind	Function
SUPER + Space	App Menu (Launcher)
SUPER + Q	Open Kitty Terminal
SUPER + C	Kill / Close Focus Window
SUPER + E	Open File Manager
SUPER + B	Open Browser
SUPER + /	Open Emoji Menu
SUPER + TAB	Open Haku Menu
SUPER + N	Open Notification Center (routes to active backend)
SUPER + ESCAPE	Emergency switch to Classic backend
SUPER + V	Open Clipboard History
SUPER + SHIFT + V	Wipe Clipboard History
SUPER + P	Screenshot
SUPER + SHIFT + P	Fullscreen Screenshot
SUPER + F11	Record Screen
SUPER + T	Toggle Cava Underbar
SUPER + Y	Wallpaper Select
SUPER + SHIFT + Y	Change Theme
SUPER + SHIFT + E	Exit Session
SUPER + SHIFT + Q	Power Menu / Shutdown
SUPER + Z	Toggle Taskbar (Classic)
SUPER + SHIFT + Z	Cycle Waybar Mode
SUPER + CTRL + Z	Toggle Waybar
SUPER + W	Toggle Floating Window (Hyprland, Niri, MangoWM)
SUPER + F	Maximize / Fullscreen Window
SUPER + SHIFT + F	Fullscreen Window (Hyprland, Niri, MangoWM)
SUPER + A / S	Focus Left / Right Window (or Arrow keys)
SUPER + SHIFT + A / S	Move / Swap Window Left / Right
SUPER + 1..9	Switch Workspace
SUPER + SHIFT + 1..9	Move Window to Workspace

• Specific Window Manager Keybindings:

Window Manager	Bind	Function
Hyprland	SUPER + D / SHIFT + D	Scroller Column Resize (+0.1 / -0.1)
	SUPER + L	Cycle Layout (scrolling, dwindle, master)
	SUPER + X	Toggle Special Workspace (Scratchpad)
	SUPER + F1	Toggle No-gap Mode
	SUPER + U / = / -	Cursor Zoom
Niri	SUPER + G	Toggle Overview
	SUPER + D / SHIFT + D	Set Column Width (+10% / -10%)
	SUPER + M / ALT + F	Maximize Window to Edges
	Mod + Shift + /	Show Hotkey Overlay
MangoWM	SUPER + G / ALT + TAB	Toggle Overview
	SUPER + D	Switch Proportion Preset
	SUPER + ALT + R	Reload Config
	SUPER + SHIFT + Arrows	Focus Monitor
	SUPER + ALT + Arrows	Tag Window to Monitor
	CTRL + ALT + Delete	Quit MangoWM
Labwc	SUPER + M	Toggle Maximize
	SUPER + S	Iconify (Minimize)
	SUPER + D	Toggle Show Desktop
	SUPER + F	Toggle Fullscreen
	ALT + GRAVE ( ` )	Open Client Menu
	ALT + Tab / SHIFT + Tab	Next / Previous Window
	ALT + WASD / SHIFT + WASD	Resize Window (+20% / -20%)
	SUPER + Arrows	Snap Window to Edge

---

Assets Located

• Custom config (your personal changes): ~/hakucfg
• Hakuspace state folder: ~/.local/state/hakuspace
• Icons: ~/.icons
• Themes: ~/.themes
• All hakuspace scripts: ~/.local/bin
• Fastfetch logo: ~/.config/fastfetch
• Wallpapers: ~/Pictures/Wallpapers
• Lively wallpapers: ~/Videos/Wallpapers

---

Documentation

Want to understand how HakuSpace works under the hood? We've written comprehensive documentation explaining the internal architecture, scripts, and theming engine.

• Architecture Overview (Start Here!)
• Management & Deployment
• Core Script Structure
• The Core Libraries
• Theming Engine & Visual Ecosystem
• System Scripts
• Utilities
• Haku Menu
• Mini-Apps (Taskbar, Desktop Icons, Rounded Screen, Edge Trigger, Cava)
• NixOS Integration
• Hikai

---

Troubleshooting

Hikai / Quickshell issues:

• Check if Hikai is running properly:

  ~/.local/bin/haku_backend.sh --check
  ~/.local/bin/haku_backend.sh --verify
  

• If Hikai fails to start, switch back to Classic with ~/.local/bin/haku_backend.sh set classic or press SUPER + ESCAPE.
• Quickshell runtime logs are saved in ${XDG_RUNTIME_DIR}/hakuspace/ (when the session runtime directory is set). Install/update terminal transcripts are saved under log/ in the repository.

Waybar / Classic issues:

• Waybar clock: Set your timezone and locale manually in the Waybar configuration to ensure the clock displays correctly.
• Waybar cava module: Install waybar-cava if you want to use the Cava module inside Classic Waybar.

My dotfiles issues:

• Run ./doctor.sh to check for broken symlinks or overwritten config files, and use ./rollback.sh if an update causes issues.
• Some features might still be missing since I mainly tested this setup for my personal use. If you need more than what's provided, you can customize it in ~/hakucfg.
• If you don't want to use certain apps (like wl-screenrec, thunar, ly, etc.), you can replace them with alternatives - just keep in mind some apps are tightly integrated into my scripts.
• If you encounter any issues during installation or configuration, feel free to ask on my TikTok, open an issue on GitHub, or join my Discord!

---

Contributing

• This is a personal dotfiles configuration. Feel free to fork and adapt it to your needs!
• Just make Pull Requests if you want to contribute to this project. I will review and merge them if they are useful for everyone.
• Tiktok / See more showcase: @hakuimaku2372
• Discord: haku-shell

Contributor	Work
hakuimaku	maintain & develop
tspillow	add waybar style - tokyo

---

Credits

See hakuspace-archive for the wallpapers used in this project: hakuspace-archive

---

License

MIT License