Skip to content

About

Session saver for Hyprland

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

94 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hyprlaunch

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.


Features

  • 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:
    1. Launch App: Starts a .desktop application or raw binary (supports non-intrusive silent flags).
    2. Run Script: Executes shell commands and scripts in optional target directories.
    3. Wait: Halts execution for a specified duration in milliseconds (ideal for tray and system daemon settling).
    4. Wait for Window: Continues when a matching Hyprland window class appears, powered by low-latency Socket2 event streaming with automatic fallback.
    5. Notify: Triggers a desktop notification to indicate progress or completions.
    6. Dispatch: Sends a command directly to Hyprland.
  • Strict Separation of Concerns (Orthogonal Design): Unlike bloated session managers that try to force window positioning, hyprlaunch lets 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 v to audit workflows for missing desktop applications, invalid script paths, excessive wait delays, invalid window waits, and empty notification headers.

Installation

Prerequisites

Make sure you have Rust and Cargo installed. You also need to be running a Hyprland session to dispatch the launches.

Pre-built Binary

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/

Build from Source

Clone the repository and build the binary:

git clone https://github.com/lehkost16/hyprlaunch.git
cd hyprlaunch
cargo build --release

The 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/).


Usage

hyprlaunch behaves contextually depending on how it is executed:

Interactive mode (TUI)

Run without arguments inside a terminal to launch the setup and management TUI:

hyprlaunch

Alternatively, you can force the TUI to open:

hyprlaunch tui

TUI Keyboard Shortcuts

  • Workflow Navigation (Left Pane):
    • Up / Down or k / 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; press 1–7 to 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+P toggles parallel launch. Adjacent Launch steps with this enabled start together.

Non-Interactive mode

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.

Launching specific workflows via CLI

You can launch a specific workflow by name directly from your terminal or shell scripts:

hyprlaunch <workflow_name>

List workflows

Print all configured workflows (the active workflow is highlighted):

hyprlaunch list

Configuration File

Your workflows and settings are stored in JSON format at: ~/.config/hyprlaunch/config.json

Environment Variable Override

You can override the default config location by setting the HYPRLAUNCH_CONFIG environment variable:

export HYPRLAUNCH_CONFIG="$HOME/custom/path/config.json"

Config Schema Example

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.


Integration with Hyprland

To automatically launch a specific workflow (or your active default workflow) when you log into Hyprland:

Hyprland Classic Config (hyprland.conf)

# 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

Modern Hyprland Lua Config (hyprland.lua / startup.lua)

-- 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 coding

License

This project is licensed under the GPL-3.0 License.

About

Session saver for Hyprland

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages