Native AI Command Surface & Launcher for Hyprland
English (UK) · Português (Brasil) · Português (Portugal) · Español · 简体中文
Native AI launcher for Hyprland — CLI agents, desktop environments, and curated cloud portals unified under a single, keyboard-driven Rofi glass interface. Nothing is hard-coded: tools appear only when genuinely installed on your system, and the entire window follows your desktop wallpaper's Material You palette in real time.
- 02 / At a Glance
- 03 / Capabilities & Engineering
- 04 / Candidate Atlas & Showcase
- 05 / Control Surface & Usage
- 06 / Requirements & Installation
- 07 / Configuration & Customisation
- 08 / Pipeline Architecture & Internals
- 09 / Troubleshooting & Diagnostics
- 10 / Lineage & Provenance
Hypr.AI eliminates the friction of switching between terminal windows, heavy IDEs, and browser tabs when orchestrating modern AI tools.
| Pillar | Technical Implementation | Architectural Guarantee |
|---|---|---|
| Runtime Detection | Dynamic candidate probing via interactive fish shell environment |
Zero stale or dead entries; auto-discovery on install/uninstall |
| Material You Glass | 60% background alpha, 1.5px top-rim lighting, live Noctalia bridge | Deep compositor blur matching current wallpaper tonal scheme |
| Protocol Safety | NUL-delimited icon streaming directly to Rofi dmenu pipe | Preserves high-resolution SVGs/PNGs without shell truncation |
| Non-Intrusive Keybinds | Conflict detection via hyprctl -j binds during automated setup |
Safe Super + I registration without overriding existing macros |
| Multi-Language Core | Automated locale resolution supporting 5 language suites | Native strings in EN-GB, PT-BR, PT-PT, ES-ES, and ZH-CN |
Under Wayland and UWSM, Hyprland launches processes with a minimal system PATH (typically limited to /usr/bin, ~/.local/bin, and ~/.cargo/bin). Environments managed via Linuxbrew (/home/linuxbrew/.linuxbrew/bin), NVM, Pyenv, or asdf are typically configured inside ~/.config/fish/config.fish within interactive guards (if status is-interactive).
If a launcher evaluates candidate binaries using a standard subshell, CLI agents installed via Brew or virtual environments become completely invisible. Hypr.AI solves this by querying fish -i for its full evaluated $PATH exactly once upon menu invocation, testing all candidate binaries against this consolidated path in native Bash. This eliminates the latency of spawning 30 separate Fish processes whilst ensuring that what is detected mirrors what actually executes.
Producing authentic glass on Wayland requires careful balance between compositor blur and surface transparency:
- Calibrated Opacity (60%): Window background
bg0is calibrated to 60% opacity (#0D0D10@0x99). Exceeding ~85% opacity chokes incoming light, rendering the compositor blur indistinguishable from flat paint. Below 50%, text legibility degrades over bright wallpapers. - Top-Only Rim Light: Authentic physical glass only catches specular illumination on its top edge. Hypr.AI applies
border: 1.5px 0px 0px 0px, avoiding full-box borders that flatten the appearance. xray = falseLayer Rule: Hyprland'sxraydirective instructs the blur shader to skip intermediate layers. However, when using modern wallpaper daemons (such as Noctalia) where the wallpaper itself occupies a full-screen layer,xray = trueskips the wallpaper, causing blur to collapse silently. Hypr.AI mandates and validatesxray = false.
Rofi's native icon protocol (-show-icons) expects a raw NUL byte (\0) between the entry text and metadata flags (e.g. entry\0icon\x1f/path/to/icon.svg). Because Bash variables cannot store NUL characters without truncating string content at the byte boundary, Hypr.AI maintains parallel arrays for labels, unique IDs, and icon paths, formatting and streaming the NUL bytes directly into the standard input pipe via printf. The selection returns purely as a numeric index (-format i), mapping directly back to candidate actions without polluting the UI with raw IDs.
Hypr.AI ships with pre-configured candidate definitions across three primary domains. Candidates remain hidden until their corresponding binaries or environments are detected.
| Domain | Supported Tools & Ecosystem Nodes | Launch Subsystem |
|---|---|---|
| CLI Agents | Claude Code, Antigravity CLI, Gemini CLI, Codex CLI, Aider, GitHub Copilot CLI, Cursor CLI, OpenCode, Goose, Ollama, Qwen Code, Crush, Mods, Plandex, Droid, OpenHands, Cline, Hermes CLI | Dedicated terminal window (kitty, ghostty, foot, alacritty, wezterm) executing fish -i -c "$cmd" |
| Desktop Environments | Claude Desktop, Antigravity 2.0, Cursor, Windsurf, Zed, LM Studio, Jan, GPT4All, AnythingLLM, Chatbox, Msty, Hermes Desktop | Native Wayland application spawn |
| Curated Web Portals | 33 curated services categorised into Chat, Search, Writing, Development, Code, and Media | Default Wayland browser (xdg-open "$url") |
Hypr.AI running under Hyprland with Noctalia Material You tonal integration
Full List of 33 Curated Web Portals (Click to Expand)
- Chat & Core Models: ChatGPT, Claude, Gemini, DeepSeek, Grok, Kimi, Qwen, Mistral, Microsoft Copilot, Poe, HuggingChat, DuckDuckGo AI.
- Search & Intelligence: Perplexity AI, Genspark, Felo, Phind, Consensus.
- Writing & Synthesis: Claude Artifacts, Notion AI, Lex, TypingMind.
- Development & Code: v0 by Vercel, Lovable, Bolt.new, Replit Agent, GitHub Copilot Web.
- Media & Generation: Midjourney, Suno, Udio, ElevenLabs, Runway Gen-3, Luma Dream Machine, Flux / Black Forest Labs.
| Input / Shortcut | Operational Context | Action Performed |
|---|---|---|
Super + I |
Global Hyprland Desktop | Toggles the Hypr.AI launcher surface |
hyprai |
Shell / Terminal Prompt | Dispatches launcher from command line |
hyprai --doctor |
Shell / Terminal Prompt | Executes complete diagnostic evaluation |
Type to Filter |
In-Menu Search Field | Real-time fuzzy filtering across names, vendors, and tags |
Enter |
Selected Row | Spawns agent in dedicated terminal, launches app, or opens portal |
Esc |
In-Menu | Dismisses launcher instantly without residual state |
↩ Back |
Portals / Settings Submenu | Navigates back to the root launcher menu |
- Compositor: Hyprland
- Menu Engine:
rofi(version 1.7+ with icon protocol support) - Shells:
bashandfish(Fish is required for interactive PATH resolution and CLI execution) - Terminal Emulator:
kitty,ghostty,foot,alacritty, orwezterm(auto-detected or configured inhyprai.conf) - Typography: Inter font family (
pacman -S inter-fonton Arch Linux) - Colour Framework (Recommended): Noctalia or Caelestia (defaults to static Dark Violet / Neon Indigo without either)
- Optional Dependencies:
libnotify(desktop notifications),uwsm(systemd user session management)
# Clone the repository
git clone https://github.com/mastermaiolo/hyprai.git
cd hyprai
# Execute installer
./install.sh- Deploys scripts, configuration schemas, and icons to
~/.config/hypr/hyprai/. - Creates the
hypraiwrapper executable in~/.local/bin/hyprai. - Registers the Material You tonal template with Noctalia (if present).
- Probes
hyprctl -j bindsto ensureSuper + Iis available; prompts for an alternative key if occupied, and appends the keybind safely between-- hyprai:begin/endmarkers in~/.config/hypr/config/binds.lua(orhyprland.lua). - Prompts before appending the required glass blur layer rule to
windowrules.lua.
Tip
After initial installation under Noctalia, cycle your wallpaper or accent colour once so Noctalia can render the tonal palette bridge file (~/.local/state/hyprai/noctalia-colors.rasi).
All configurations live in human-readable text files inside ~/.config/hypr/hyprai/config/:
| Configuration File | Operational Purpose |
|---|---|
config/tools.conf |
Candidate definitions for CLI agents and desktop applications |
config/sites.conf |
Curated AI web portals, grouped by functional categories |
config/hyprai.conf |
Runtime preferences (e.g. terminal = kitty, or leave empty for auto-detection) |
rofi/user.rasi |
Optional user overrides (custom geometry, offsets, widths, fonts) |
Important
The ./install.sh script never overwrites existing .conf files or user.rasi upon re-execution. Your custom additions and curation remain untouched during updates.
Add a line to ~/.config/hypr/hyprai/config/tools.conf:
# id | icon | Name | Subtext | category | candidates | svg | args
myagent|🤖|My Agent|Custom Lab|cli|myagent;myagent-cli|myagent.svg|--chatcategory:cli(launches in interactive fish terminal) ordesktop(launches as graphical application).candidates: Semicolon-separated list of executable names or paths. Probed in sequence; the first match wins. Bare names resolve via$PATH; paths starting with~or/are checked directly.svg: Vector icon file inside~/.config/hypr/hyprai/svg/(falls back to emoji in column 2).args: Optional static arguments (useful when a single binary serves both CLI and GUI modes).
Add a line to ~/.config/hypr/hyprai/config/sites.conf:
# id | icon | Name | category | url | svg
myportal|🌐|My Portal|chat|https://example.ai|portal.svgAvailable portal categories: chat, search, write, dev, code, media.
To reposition the window (for instance, beneath a top bar), create ~/.config/hypr/hyprai/rofi/user.rasi:
/* ~/.config/hypr/hyprai/rofi/user.rasi */
window {
location: north;
y-offset: 120px;
width: 720px;
}
hyprai/
├── assets/
│ ├── readme/ # Modular design system SVGs (hero, capabilities, etc.)
│ └── screenshot.webp # Physical UI capture
├── config/
│ ├── hyprai.conf # Terminal emulator & general preferences
│ ├── sites.conf # Curated web portals
│ └── tools.conf # CLI agents & desktop app candidates
├── rofi/
│ └── hyprai.rasi # Design system stylesheet (4px grid, radii, tokens)
├── svg/ # Vector icon library for native Rofi protocol
├── theme/
│ └── noctalia.rasi.tmpl # Material You template compiled by Noctalia
├── ui/
│ └── launcher.sh # Core orchestration & probing engine
├── install.sh # Idempotent installer & keybind injector
├── uninstall.sh # Clean uninstaller
├── DESIGN.md # Coherent-design tokens & optical specifications
└── SOBRE.md # Portuguese architectural manifesto
Always begin diagnostic investigation with the built-in diagnostic harness:
hyprai --doctorhyprai --doctor inspects installed dependencies, terminal detection, active theme source, detected candidates, syntax anomalies, keybind status, and compositor layer rules.
1. A tool I have installed does not appear in the menu
The candidate executable name in tools.conf likely differs from the binary name on your system.
- Run
which <tool-name>in an interactive Fish terminal to locate the binary. - Verify if the binary name matches the
candidatesfield intools.conf. - Candidate detection fails silently by design to keep the menu clean. Add your alias or binary name to the candidate list separated by a semicolon (
;).
2. The menu appears completely opaque without glass blur
- Missing Layer Rule: Wayland layer-shell surfaces receive no blur in Hyprland without an explicit rule targeting their namespace. Re-run
./install.shand accept the glass exception. xray = trueEnabled: If your layer rule specifiesxray = true, the compositor skips intermediate layers. Because Noctalia wallpaper occupies a layer, the blur bypasses the wallpaper entirely, rendering the surface transparent or flat. Re-run./install.shor ensurexray = falsein your configuration.- Excessive Opacity: If
bg0alpha is set higher than 85%, incoming blur is blocked and reads as flat paint. Hypr.AI defaults to 60%.
3. Screenshots display glass, but physical monitors show flat surfaces
Tools like grim capture frame buffers prior to the compositor's blur pass. Even 5% transparency reveals sharp wallpaper details in screenshots (which the brain interprets as glass), while the physical display shows uniform blur. Always calibrate optical opacity based on direct monitor observation.
4. Colours do not adapt when changing wallpapers in Noctalia
Noctalia renders templates upon wallpaper or scheme transitions. If the palette desynchronises, force an update via:
noctalia msg config-reload && noctalia msg templates-apply
- Architecture: Directly derived from the conventions, ergonomics, and Wayland menu architecture of HyprVision.
- Design System: Follows the coherent-design methodology — strict 4px grid, concentric border radii (24px window, 16px container, 8px child elements), and verified OKLCH palettes maintaining WCAG contrast ratios ≥ 4.5:1. Complete specifications are documented in DESIGN.md.
- Author: Master Maiolo · MAIOLO / SYSTEMS LAB.
This project is licensed under the MIT Licence. See the LICENSE file for complete details.