hyprorbit v0.1.2

Lightweight workspace orchestration for Hyprland power users.

hyprorbit is a stateful daemon + client system for Hyprland workspace management, written in Go.

Donate · Report Bug · Request Feature

Switching projects in Hyprland can break your layout - windows scatter and workspace hotkeys change meaning. hyprorbit introduces orbits - mirrored workspace sets with identical keybindings. Switch between work, personal, or debug modes instantly while keeping muscle memory intact.

Core idea:

• Each app → fixed workspace
• Each workspace → consistent hotkey
• Some apps are global, others need an instance per-context

hyprorbit module jump code   # jump to your code workspace  
hyprorbit module focus comm  # focus or launch your comm app  
hyprorbit orbit next         # switch orbit 

• Orbit contexts - separate sets of workspaces for different projects
• Stable hotkeys - same workspace-keybindings across all orbits
• Focus-or-launch - focus windows in current orbit instead of launching
• Very low latency via persistent daemon

• Hyprland compositor
• Go 1.21+

# Clone and build
git clone https://github.com/xarcdotdev/hyprorbit.git
cd hyprorbit
make

# Install to PATH (recommended)
sudo cp hyprorbit hyprorbitd /usr/local/bin/

# Recommended: via Hyprland Config (order is important here)
exec-once = hyprorbitd # start daemon
exec-once = hyprorbit init --autostart # for workspace initialization

# Or manually for testing
./hyprorbitd

# Or with custom config
./hyprorbitd --config ~/.config/hyprorbit/config.yaml

Add to your ~/.config/hypr/hyprland.conf:

→ Example Hyprland Keybindings

# Quick workspace jumping (stable across orbits)
bind = SUPER, 1, exec, hyprorbit module jump code
bind = SUPER, 2, exec, hyprorbit module focus comm
bind = SUPER, 3, exec, hyprorbit module focus gfx

# Orbit switching
bind = SUPER, comma, exec, hyprorbit orbit prev
bind = SUPER, period, exec, hyprorbit orbit next
bind = SUPER ALT, 1, exec, hyprorbit orbit set alpha
bind = SUPER ALT, 2, exec, hyprorbit orbit set beta

# Focus Applications
bind = SUPER, C, exec, hyprorbit module focus coding
bind = SUPER, E, exec, hyprorbit module focus email

# Create temporary workspace inside of orbit & move focused window there
bind = SUPER, N, exec, hyprorbit window move current module:create

# Move all windows on current workspace to specific module in another orbit
bind = SUPER ALT, 1, exec hyporbit window move workspace orbit:alpha/module:code

# Move all windows (globally) to first module workspace of current orbit
bind = SUPER ALT CTRL, M, exec hyprorbit window move all module:index:1

See hyprorbit --help for full options.

(back to top)

Orbits: Independent workspace contexts (e.g., alpha, beta, gamma)

• Separate environments for different projects/contexts
• Default labels: α, β, γ
• Each orbit maintains its own window instances

Modules: Workspace categories bound to consistent hotkeys (e.g., code, comm, gfx)

• SUPER+1 → "code" module in whichever orbit you're in
• Generate orbit-specific workspaces: code-alpha, comm-beta, etc.
• Windows bind to modules via pattern matching

→ Full Command Reference

• Default: ~/.config/hyprorbit/config.yaml
• Override: --config <path> flag
• Environment: HYPR_ORBITS_SOCKET for custom socket path

→ Config Schema

→ Waybar Setup

Waybar example:

~/.config/waybar/config.jsonc

"custom/hyprorbit#orbit": {
  "format": "{text}-{alt}",
  "return-type": "json",
  "exec": "hyprorbit module watch --waybar --waybar-config ~/.config/hyprorbit/waybar.yaml",
  "restart-interval": 0,
  "escape": true,
  "max-length": 20,
  "on-click": "hyprorbit orbit next",
  "on-click-right": "hyprorbit orbit prev",
  "tooltip": true
}

~/.config/hyprorbit/waybar.yaml

module_watch:
  text: ["module", "workspace"]
  tooltip: ["orbit_label", "workspace"]
  alt: ["workspace"]
  class:
    sources: ["module", "orbit"]

(back to top)

• ✅ Initial Configuration system
• ✅ Orbit management
• ✅ Module focus/jump commands
• ✅ Window matching system
• ✅ Shell Completion Script
• ✅ Waybar/status support
• ✅ Multi Monitor Support
• ✅ Client-server architecture (IPC)
• ✅ Module seeding (populate workspace with multiple apps)
• ✅ Support for Hyprland tag for adressing windows
• ✅ Global window targeting with --global flag for cross-orbit window operations

• Add sane defaults for generated config (multiple browsers, email clients IDEs etc.)
• Add config parameter for assigning workspaces/modules to monitors
• Make Orbit-Alignment across monitors optional (Have independent orbits on each monitor)
• Add window destroy command for orbit/workspace based cleanup
• Configurable notifications

Issues and PRs welcome!

# Clone repository
git clone https://github.com/xarcdotdev/hyprorbit.git
cd hyprorbit

# Build both binaries
make

# Run tests
make test

This project is licensed under the MIT License. See LICENSE for details.

(back to top)