Hyprinator

Hyprinator is a tiny launcher for Hyprland that gives you a tmuxinator-inspired YAML workflow for desktop workspaces.

You define which commands should exist on each workspace, run one command, and Hyprinator will:

1. close existing windows only on the referenced workspaces,
2. re-create the workspace layout from your YAML,
3. default plain command strings to your configured terminal in the right working directory.

Why this exists

• You want repeatable workspace bootstrapping, not manual app shuffling.
• You like tmuxinator-style concepts (root, windows, panes) but for Hyprland windows.
• You want a safe reset scope: only the workspaces you define are cleared.

Install

From this project directory:

chmod +x ./bin/hyprinator
ln -sf "$(pwd)/bin/hyprinator" "$HOME/.local/bin/hyprinator"

Then run:

hyprinator --help

Quick start

Create a file named .tmuxinator.yml in your project:

name: trailbox
root: ~/code/northforge/trailbox

windows:
  - "1":
      panes:
        - npm run dev
        - bundle exec rails s
        - app: ghostty
  - "2":
      panes:
        - app: chromium --new-window
  - "3":
      root: ~/code/northforge/trailbox/api
      panes:
        - bundle exec sidekiq
        - app: ghostty -e btop

Run:

hyprinator

DSL reference

Hyprinator intentionally supports a focused subset of tmuxinator-like concepts.

Top-level keys

• name (optional)
• root (optional, default working directory for terminal launches)
• windows (required)

windows

windows is a YAML list where each entry is a single-key map:

windows:
  - "1": <window-value>
  - "2": <window-value>

The key must be numeric ("1", "2", etc.) and maps directly to the Hyprland workspace id.

Window values

Supported forms:

1. String (defaults to terminal command):

- "1": npm run dev

2. Object with optional root and panes:

- "3":
    root: ~/code/project/api
    panes:
      - npm run dev
      - app: chromium

Pane entries

• Plain string: treated as a shell command in your default terminal via xdg-terminal-exec.
• Object with app: treated as a raw app command and launched directly.

Examples:

panes:
  - npm run dev
  - app: ghostty
  - app: firefox --new-window

Command behavior

For plain string commands, Hyprinator runs:

xdg-terminal-exec --dir=<resolved-root> -- bash -lc '<your-command>; exec bash'

resolved-root is:

1. window root if provided,
2. otherwise top-level root if provided,
3. otherwise directory containing the YAML config file.

CLI

hyprinator [options]

Options:

• -p, --project-config PATH Use a specific config file.
• --dry-run Print planned close/launch commands without executing.
• --delay-ms N Delay between launches (default: 120).
• -h, --help Show help.

Default config lookup when -p is omitted:

1. ./.tmuxinator.yml
2. ./.hyprinator.yml

Safety model

• Hyprinator only closes windows on workspaces referenced in your config.
• Other workspaces are untouched.
• --dry-run lets you inspect every action before running it.

Examples

See:

• examples/basic.yml
• examples/full.yml

Tests

Run:

ruby test/run.rb

The tests use a built-in harness and do not require external gems.

Hyprland keybinding

Add to ~/.config/hypr/bindings.conf:

bind = SUPER SHIFT, S, exec, hyprinator -p ~/code/teevans/hyprinator/examples/full.yml