hyprlaunch is a terminal-based Workflow Orchestrator for the Hyprland window manager. It provides an interactive Terminal User Interface (TUI) to define, configure, and reorder structured sequences of steps ("workflows") that you want to execute together.
Unlike state-restoring session managers, hyprlaunch lets you organize workspace mapping rules, scripts, notifications, and readiness checks into reusable workflows. Steps stay ordered by default, with optional parallel app launches for independent startup tasks.
- Interactive TUI Dashboard: Keyboard-driven sidebar and editor panes to manage workflows and re-arrange execution order.
- Workflow Execution Pipeline: Supports ordered, modular steps without stepping on window manager rules:
- Launch App: Starts a
.desktopapplication or raw binary (supports non-intrusivesilentflags). - Run Script: Executes shell commands and scripts in optional target directories.
- Wait: Halts execution for a specified duration in milliseconds (ideal for tray and system daemon settling).
- Wait for Window: Continues when a matching Hyprland window class appears, powered by low-latency Socket2 event streaming with automatic fallback.
- Notify: Triggers a desktop notification to indicate progress or completions.
- Dispatch: Sends a command directly to Hyprland.
- Launch App: Starts a
- Strict Separation of Concerns (Orthogonal Design): Unlike bloated session managers that try to force window positioning,
hyprlaunchlets Hyprland manage windows (window_rules.lua), while focusing purely on declarative process lifecycle and orchestration timing. - Fail-safe Instance Detection: Automatically detects and connects to the active Hyprland instance signature even when launched from headless/systemd user sessions.
- Parallel App Launch: Consecutive app-launch steps can start together; other step types remain ordered barriers.
- Silent Launch & Background Integration: Seamlessly launch background tools or tray apps without stealing focus or interrupting current workspace flow.
- Failure Policy: Choose whether a workflow continues after a failed step or skips the remaining steps.
- Integrated Health Check Scanner: Press
vto audit workflows for missing desktop applications, invalid script paths, excessive wait delays, invalid window waits, and empty notification headers.
Make sure you have Rust and Cargo installed. You also need to be running a Hyprland session to dispatch the launches.
Download the pre-compiled hyprlaunch-linux-x86_64.tar.gz from the Latest GitHub Release, unpack it, and place it in your PATH:
tar -xzf hyprlaunch-linux-x86_64.tar.gz
chmod +x hyprlaunch
mv hyprlaunch ~/.local/bin/Clone the repository and build the binary:
git clone https://github.com/lehkost16/hyprlaunch.git
cd hyprlaunch
cargo build --releaseThe compiled binary will be located at target/release/hyprlaunch. You can move it to a folder in your PATH (such as /usr/local/bin or ~/.local/bin/).
hyprlaunch behaves contextually depending on how it is executed:
Run without arguments inside a terminal to launch the setup and management TUI:
hyprlaunchAlternatively, you can force the TUI to open:
hyprlaunch tui- Workflow Navigation (Left Pane):
Up/Downork/j: Navigate workflows list.Space: Set the selected workflow as the default active startup workflow (indicated by a★).Enter: Save and run the selected workflow; progress and step results stay visible in the TUI.c: Create a new workflow.r: Rename the selected workflow.y: Duplicate/Clone the selected workflow.d: Delete the selected workflow.v: Run health audit checks on the selected workflow steps.p: Toggle the selected workflow's failure policy between Continue and Stop.Tab/Right/l: Switch pane to edit steps in the selected workflow.q/Esc: Quit the application.
- Step Navigation & Editing (Right Pane):
Tab/Left/h: Switch back to the workflow list.a: Add a new step to the workflow (opens a selector; press1–7to choose a type directly).- Application search accepts partial names and fuzzy character matches, ranked by relevance.
e: Edit all parameters of the selected step (opens a multi-field editor).y: Duplicate the selected step directly below it.d/Delete: Remove the selected step.Enter: Test launch / run only the selected step immediately in the background.Shift+Up/Shift+Down: Move the selected step up or down in the startup sequence.- In a Launch step editor,
Ctrl+Ptoggles parallel launch. Adjacent Launch steps with this enabled start together.
If executed without arguments in a non-interactive environment (such as when called from hyprland.conf), hyprlaunch will automatically launch the currently active workflow (marked with ★) and then exit.
You can launch a specific workflow by name directly from your terminal or shell scripts:
hyprlaunch <workflow_name>Print all configured workflows (the active workflow is highlighted):
hyprlaunch listYour workflows and settings are stored in JSON format at:
~/.config/hyprlaunch/config.json
You can override the default config location by setting the HYPRLAUNCH_CONFIG environment variable:
export HYPRLAUNCH_CONFIG="$HOME/custom/path/config.json"Here is how your config.json might look:
{
"active_workflow": "coding",
"workflows": {
"coding": {
"name": "coding",
"on_error": "continue",
"steps": [
{
"type": "notify",
"title": "Developer Workspace",
"body": "Booting development environment..."
},
{
"type": "launch",
"desktop": "firefox.desktop",
"workspace": "1",
"silent": false,
"parallel": true
},
{
"type": "launch",
"desktop": "kitty.desktop",
"workspace": "2",
"silent": true,
"monitor_cond": "HDMI-A-1?3:2",
"parallel": true
},
{
"type": "wait_window",
"class": "kitty",
"timeout_ms": 15000
},
{
"type": "script",
"command": "git pull",
"dir": "/home/user/projects/hyprlaunch"
}
]
}
}
}Every workflow must set on_error, and every launch step must set parallel. Set on_error to "stop" to skip subsequent steps after a failure, or "continue" to keep running them. Consecutive launch steps with parallel: true are dispatched concurrently; use false for sequential launches. If a parallel step fails under the Stop policy, its already-started peers finish before later steps are skipped. Use wait_window after launching an app when a later action depends on its window being ready, instead of guessing with a fixed delay. The loader reads only the current workflow schema; it does not migrate older profile-format files.
To automatically launch a specific workflow (or your active default workflow) when you log into Hyprland:
# Launch a specific workflow (e.g., "default", "coding", "Nor")
exec-once = hyprlaunch <workflow_name>
# Or launch the currently active workflow (marked with ★ in TUI)
exec-once = hyprlaunch-- Launch a specific workflow
hl.exec_cmd("hyprlaunch <workflow_name>")
-- Or launch the active workflow
hl.exec_cmd("hyprlaunch")You can also create keybindings to easily switch workflows:
# Switch to and launch the "gaming" workflow
bind = $mainMod, G, exec, hyprlaunch gaming
# Switch to and launch the "coding" workflow
bind = $mainMod, C, exec, hyprlaunch codingThis project is licensed under the GPL-3.0 License.