garlaunch

Modes

garlaunch supports four modes, each providing a different set of items to search and select.

drun (Desktop Apps)

Desktop entry mode parses .desktop files from XDG application directories.

Search Paths

Parsing Rules

• Uses freedesktop_entry_parser crate
• Skips entries with NoDisplay=true or Hidden=true
• Requires Name and Exec attributes
• Extracts Comment for description, Icon for icon name
• Cleans Exec field codes (%f, %F, %u, %U, etc.)
• Deduplicates entries (first path wins)
• Sorts alphabetically by name

Exec Field Cleaning

Desktop entry Exec fields contain field codes (%f = single file, %F = multiple files, etc.). garlaunch strips these:

run (Commands)

Command execution mode lists all executables from $PATH.

Discovery Process

1. Splits $PATH by colon (:)
2. Scans each directory for files
3. Checks executable permission (mode & 0o111)
4. Skips directories and hidden files (starting with .)
5. Deduplicates (first in PATH wins)
6. Sorts alphabetically

Execution

When you select an item, garlaunch executes it via shell (sh -c) to support pipes, redirects, and environment expansion.

Use Cases

• Quick command execution without terminal
• Launch GUI apps without .desktop files
• Run scripts from ~/bin or ~/.local/bin

window (Switcher)

Window switcher mode shows all windows from gar window manager.

gar Integration

• Connects to gar via Unix socket ($XDG_RUNTIME_DIR/gar.sock)
• Sends get_windows IPC request
• Parses JSON response with window list
• Displays title, class, instance, workspace
• On selection, sends focus_window IPC request

Window Info

Requirements

Window mode requires gar window manager to be running. If gar.sock doesn't exist, mode loads zero items.

script (Custom)

Script mode executes an external script that provides items via JSON protocol.

Protocol Overview

Initial Items Message

{
  "items": [
    {
      "id": "item1",
      "name": "First Item",
      "description": "Optional description",
      "icon": "optional-icon-name",
      "data": {"custom": "data"}
    },
    {
      "id": "item2",
      "name": "Second Item"
    }
  ]
}

Selection Message

{
  "selected": {
    "id": "item1",
    "name": "First Item",
    "description": "Optional description",
    "icon": "optional-icon-name",
    "data": {"custom": "data"}
  }
}

Action Response

// Launch a command
{"action": "launch", "command": "firefox"}

// Close launcher
{"action": "close"}

// Switch to another mode
{"action": "switch", "mode": "drun"}

// Custom action (returns to caller)
{"action": "custom", "data": {"foo": "bar"}}

Fuzzy Search

garlaunch uses the nucleo matcher for fast fuzzy searching with smart behavior.

Features

• Smart Case: Lowercase query matches case-insensitive, uppercase forces case-sensitive
• Normalization: Handles diacritics and unicode normalization
• Multi-Field: Matches against both name and description
• Scoring: Results sorted by match quality

Matching Algorithm

For each item, nucleo computes a score based on:

• Character positions (earlier matches score higher)
• Consecutive characters (word starts preferred)
• CamelCase boundaries
• Query coverage (more chars matched = better score)

Examples

Frecency Sorting

garlaunch tracks how often and recently you launch applications, using a frecency algorithm (frequency + recency) with exponential decay to rank results. Frequently used applications appear higher in the list even before you start typing.

How It Works

• Each launch records a score bump of +1.0 for that application
• Existing scores decay exponentially based on time since last use
• Default half-life is 1 week (168 hours) — an app used once a week ago has score ~0.5
• Scores combine with fuzzy match quality when a search query is active

Cache Location

Frecency data is stored per-mode in tab-separated text files:

~/.cache/garlaunch/drun.cache    # Desktop application launches
~/.cache/garlaunch/run.cache     # Command execution launches
~/.cache/garlaunch/window.cache  # Window switch selections

Cache Format

Each line contains: id score last_access_timestamp

# garlaunch frecency cache v1
firefox.desktop	3.847521	1739523600
alacritty.desktop	1.923760	1739437200
code.desktop	0.961880	1739350800

Delete a cache file to reset frecency for that mode. Entries are sorted by score descending.

UI & Rendering

garlaunch uses gartk for X11 window management and Cairo/Pango rendering.

Popup Window

The launcher appears as a centered popup window.

Window Configuration

• Type: Popup window (override-redirect)
• Size: 600x400 pixels
• Position: Centered on primary monitor, upper third vertically
• Properties: Transparent background support, no decorations
• Input: Keyboard grab for exclusive input

Monitor Detection

Uses gartk_x11::primary_monitor() to detect the primary monitor via RandR extension. Window centered on this monitor's geometry.

Keyboard Grab

The window grabs keyboard focus exclusively (window.grab_keyboard()). This prevents input from reaching other windows. Grab released when launcher closes.

Input Field

The input field shows the search query with a prompt and blinking cursor.

Components

• Prompt: "Search:" (customizable via --prompt)
• Input Text: User's current query
• Cursor: 2px wide vertical bar at cursor position
• Background: Rounded rectangle with theme.input_background color

Cursor Movement

Cursor tracks character position (not byte index). Supports Left/Right arrow keys, Home/End for jump to start/end.

Text Editing

• Char key: Insert at cursor, advance cursor
• Backspace: Delete char before cursor
• Delete: Delete char after cursor
• Space: Insert space at cursor

Item List

Below the input field is a scrollable list of filtered items.

Layout

• Max Visible: 10 items at once
• Scrolling: Scroll offset adjusts when selection moves out of view
• Selection: Highlighted with theme.item_selected_background
• Item Height: Font size + 2× item padding

Item Rendering

• Name: Left-aligned, theme.font_size, vertically centered
• Description: Right of name, 85% font size, ellipsized if too long
• Colors: Selected items use theme.item_selected_foreground

Item Counter

Bottom-right corner shows "X/Y" where X = visible filtered items, Y = total items.

Theming

garlaunch uses gartk Theme system for consistent appearance.

Theme Colors

Current Behavior

Currently uses Theme::dark() hardcoded. Future versions will support custom themes via config file or gartk theme system integration.

Keyboard Control

All interaction is keyboard-driven through gartk's event system.

Key Handling Flow

Navigation Keys

Action Keys

Daemon & IPC

garlaunch can run as a daemon to provide IPC control via garlaunchctl.

Daemon Mode

In daemon mode, garlaunch listens for IPC commands and spawns launcher instances.

Event Loop

Process Spawning

When a show/toggle command arrives, daemon spawns a new garlaunch process with appropriate --mode argument. Each launcher instance runs independently.

Socket Location

$XDG_RUNTIME_DIR/garlaunch.sock (fallback: /tmp/garlaunch.sock)

garlaunchctl

garlaunchctl is a control client for sending commands to the daemon.

Commands

Fallback Behavior

If daemon isn't running (socket not found or connection refused), garlaunchctl spawns garlaunch directly for show/toggle commands. This provides graceful degradation.

IPC Protocol

JSON messages over Unix socket.

Request Format

{
  "command": "show",
  "args": {
    "mode": "drun",
    "source": null
  }
}

Response Format

// Success
{
  "success": true,
  "data": null,
  "error": null
}

// Error
{
  "success": false,
  "data": null,
  "error": "Daemon not running"
}

gar Integration

garlaunch integrates with gar window manager for window switching mode.

GarClient

The GarClient struct handles IPC communication with gar via Unix socket.

Socket Path

$XDG_RUNTIME_DIR/gar.sock (fallback: /tmp/gar.sock)

IPC Methods

Availability Check

GarClient::is_available() checks if gar.sock exists. Window mode silently loads zero items if gar isn't running.

Script Protocol

External scripts provide custom menus via JSON over stdin/stdout.

Example Script

#!/bin/bash

# Output items
cat <<EOF
{
  "items": [
    {"id": "1", "name": "Option 1", "description": "First choice"},
    {"id": "2", "name": "Option 2", "description": "Second choice"},
    {"id": "3", "name": "Close", "description": "Close menu"}
  ]
}
EOF

# Read selection
read -r selection

# Parse selection and output action
item_id=$(echo "$selection" | jq -r '.selected.id')

case "$item_id" in
  1)
    echo '{"action": "launch", "command": "notify-send \"Option 1 selected\""}'
    ;;
  2)
    echo '{"action": "launch", "command": "notify-send \"Option 2 selected\""}'
    ;;
  3)
    echo '{"action": "close"}'
    ;;
esac

Usage