"When all you have is a hammer, everything looks like a nail"

paru -S hamr

Hamr is an extensible launcher for Hyprland built with Quickshell. Extend it with plugins in any language using a simple JSON protocol.

Minimalist UI - Clean, modern, no visual clutter. Just a search bar and results. No sidebars, tabs, or menus unless absolutely necessary.

Zero Configuration - Works out of the box with sensible defaults. Settings exist but you should never need to touch them.

Minimum Interactions - Every feature optimized for fewest possible keystrokes. Search, Enter, done.

Learns Your Habits - Frecency ranking means frequently-used items rise to the top automatically. Type "ff" once to launch Firefox, and "ff" becomes your shortcut forever.

Keyboard-First - Full functionality without touching the mouse. Vim-style navigation (Ctrl+J/K), quick action shortcuts (Ctrl+1-6), and muscle-memory-friendly bindings.

Your Shortcuts, Your Way - First time, type "move to workspace 3". Next time, just "w3". Hamr learns your patterns and creates personal shortcuts automatically. No configuration, no aliases to maintain.

• Frecency-based ranking - Results sorted by frequency + recency (inspired by zoxide)
• Learned search affinity - System learns your search shortcuts (type "q" to find QuickLinks if that's how you found it before)
• Pattern-matched plugins - Plugins can auto-trigger on patterns (e.g., math expressions, URLs) without explicit prefixes
• Fuzzy matching - Fast, typo-tolerant search powered by fuzzysort, includes desktop entry keywords (e.g., "whatsapp" finds ZapZap)
• Extensible plugins - Language-agnostic handlers with simple JSON protocol (Python, Bash, Go, Rust, etc.)
• History tracking - Search, plugin actions, and shell command history
• Smart suggestions - Context-aware app suggestions based on time, workspace, and usage patterns
• Preview panel - Drawer-style side panel shows rich previews (images, markdown, metadata) on hover/selection; pin previews to screen
• Draggable & persistent position - Drag the launcher anywhere on screen; position remembered across sessions
• State restoration - Click outside to dismiss, reopen within 30s to resume where you left off (configurable)

These shortcuts are fully customizable. See Customizing Prefix Shortcuts for details.

Type math expressions directly - no prefix needed. Examples: 2+2, sqrt(16), 10c (celsius), $50 to EUR, 20% of 32, 10ft to m

Powered by qalculate - supports 150+ currencies, 100+ units, percentages, and advanced math.

All plugins are indexed and searchable directly from the main bar - no prefix required. Just type what you want (e.g., "clipboard", "emoji", "power") and Hamr finds it. Prefix shortcuts like /, ~, ; are optional conveniences, not requirements.

Forgot which keybinding moves a window to workspace 3? Can't remember the shortcut for toggling floating mode? No problem. Just type what you want in plain English and Hamr handles the rest.

The hyprland plugin provides natural language access to Hyprland window management - no need to memorize keybindings or dig through config files.

Window Management:

• toggle floating, fullscreen, maximize, pin, center window
• close window, focus left/right/up/down
• move window left/right/up/down, swap left/right/up/down

Workspace Navigation:

• workspace 3, go to 5, next workspace, previous workspace
• move to 2, move to workspace 4 silent
• scratchpad, empty workspace

Window Groups (Tabs):

• create group - Make current window a group
• join group left/right - Add window to adjacent group
• remove from group, next in group, prev in group

Global Shortcuts: Every app that registers DBus global shortcuts becomes instantly searchable. That obscure "Toggle side panel" shortcut from your browser extension? Just type side panel. The screen recording hotkey you set up months ago? Type record. No need to remember Ctrl+Alt+Shift+whatever - describe what you want and Hamr finds it.

Monitor Control:

• next monitor, prev monitor
• move workspace to monitor, swap workspaces

Commands are saved to history for quick access. Even better: after using "move to workspace 3" a few times, just type w3 or m3 - Hamr learns your shortcuts automatically. Type /hyprland to browse all available commands, or search directly from the main bar.

Requirements: Hyprland on Linux (Quickshell is Wayland-only and Hamr uses Hyprland-specific APIs)

# Using paru (or yay, etc.)
paru -S hamr

# Clone the repository
git clone https://github.com/stewart86/hamr.git
cd hamr

# Run the install script (auto-installs dependencies)
./install.sh

# Using paru (or yay, etc.)
paru -S quickshell python python-click python-loguru python-tqdm \
    python-gobject gnome-desktop-4 wl-clipboard cliphist fd fzf \
    xdg-utils libnotify gtk3 hyprland libpulse jq libqalculate \
    ttf-material-symbols-variable ttf-jetbrains-mono-nerd ttf-readex-pro

# Optional
paru -S tesseract imagemagick bitwarden-cli slurp wf-recorder

git clone https://github.com/stewart86/hamr.git
cd hamr

# Create config directories
mkdir -p ~/.config/quickshell ~/.config/hamr/plugins
ln -s "$(pwd)" ~/.config/quickshell/hamr

# Install Python dependencies
pip install click loguru tqdm PyGObject

# Install system packages (example for Fedora)
sudo dnf install fd-find fzf wl-clipboard jq qalculate

# Install fonts (see font section below)

mkdir -p ~/.local/share/fonts
# Extract/copy downloaded fonts to ~/.local/share/fonts/
fc-cache -fv

1. Add Hyprland keybinding (required)

Hamr starts hidden and listens for a toggle signal. Add this to ~/.config/hypr/hyprland.conf:

# Toggle Hamr with Ctrl+Space
bind = Ctrl, Space, global, quickshell:hamrToggle

# Or use Super+Space
# bind = Super, Space, global, quickshell:hamrToggle

2. Start Hamr

hamr

After starting, press your keybind (e.g., Ctrl+Space) to open Hamr.

3. (Optional) Auto-start with Hyprland

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

exec-once = hamr

AUR:

paru -Syu hamr

Manual installation:

cd /path/to/hamr
./install.sh --update

AUR:

sudo pacman -R hamr
# Optionally remove user data:
rm -rf ~/.config/hamr

Manual installation:

./install.sh --uninstall

./install.sh --check

journalctl --user -u quickshell -f

WARN: Read of colors.json failed: File does not exist

WARN: Read of quicklinks.json failed: File does not exist

[
  {"name": "GitHub", "url": "https://github.com", "icon": "code"}
]

# Install cliphist (Arch: pacman -S cliphist wl-clipboard)

# Add to Hyprland startup
exec-once = wl-paste --type text --watch cliphist store
exec-once = wl-paste --type image --watch cliphist store

Hamr loads plugins from two locations:

• Built-in plugins: <hamr>/plugins/ - Included with Hamr, read-only
• User plugins: ~/.config/hamr/plugins/ - Your custom plugins

User plugins with the same name as built-in plugins will override them.

Each plugin is either:

• A folder with manifest.json + handler executable (multi-step plugins)
• An executable script (simple one-shot actions)

Language agnostic: Plugins communicate via JSON over stdin/stdout. Use Python, Bash, Go, Rust, Node.js - any language that can read/write JSON.

mkdir -p ~/.config/hamr/plugins/hello

{
  "name": "Hello World",
  "description": "A simple greeting plugin",
  "icon": "waving_hand"
}

#!/usr/bin/env python3
import json
import sys

def main():
    input_data = json.load(sys.stdin)
    step = input_data.get("step", "initial")

    if step == "initial":
        print(json.dumps({
            "type": "results",
            "results": [
                {"id": "english", "name": "Hello!", "icon": "language"},
                {"id": "spanish", "name": "Hola!", "icon": "language"},
            ]
        }))
        return

    if step == "action":
        selected_id = input_data.get("selected", {}).get("id", "")
        print(json.dumps({
            "type": "card",
            "card": {
                "title": "Greeting",
                "content": f"You selected: {selected_id}",
                "markdown": True
            }
        }))

if __name__ == "__main__":
    main()

chmod +x ~/.config/hamr/plugins/hello/handler.py

{
  "step": "initial|search|action",
  "query": "user's search text",
  "selected": {"id": "selected-item-id"},
  "action": "action-button-id",
  "session": "unique-session-id"
}

{
  "type": "results",
  "results": [
    {
      "id": "unique-id",
      "name": "Display Name",
      "description": "Optional subtitle",
      "icon": "material_icon_name",
      "thumbnail": "/path/to/image.png",
      "actions": [{"id": "copy", "name": "Copy", "icon": "content_copy"}]
    }
  ],
  "placeholder": "Custom placeholder...",
  "inputMode": "realtime",
  "pluginActions": [
    {"id": "add", "name": "Add", "icon": "add_circle"},
    {"id": "wipe", "name": "Wipe", "icon": "delete_sweep", "confirm": "Are you sure?"}
  ]
}

{
  "type": "card",
  "card": {"title": "Title", "content": "Markdown **content**", "markdown": true}
}

{
  "type": "execute",
  "execute": {
    "command": ["xdg-open", "/path/to/file"],
    "name": "Open file.pdf",
    "close": true
  }
}

{
  "type": "imageBrowser",
  "imageBrowser": {
    "directory": "~/Pictures",
    "title": "Select Image",
    "enableOcr": true,
    "actions": [{"id": "set_wallpaper", "name": "Set Wallpaper", "icon": "wallpaper"}]
  }
}

{
  "type": "form",
  "form": {
    "title": "Add Note",
    "submitLabel": "Save",
    "fields": [
      {"id": "title", "type": "text", "label": "Title", "required": true},
      {"id": "content", "type": "textarea", "label": "Content", "rows": 6}
    ]
  },
  "context": "add_note"
}

"pluginActions": [
  {"id": "add", "name": "Add", "icon": "add_circle"},
  {"id": "wipe", "name": "Wipe All", "icon": "delete_sweep", "confirm": "Wipe all? This cannot be undone."}
]

{
  "name": "Top CPU",
  "icon": "speed",
  "poll": 2000
}

#!/bin/bash
# ~/.config/hamr/plugins/screenshot
grim -g "$(slurp)" - | wl-copy
notify-send "Screenshot copied"

Hamr learns your search habits and creates automatic shortcuts. No configuration needed.

How it works:

1. Type "ff", scroll to "Firefox", press Enter
2. Next time you type "ff", Firefox appears at the top
3. The system remembers the last 5 search terms for each item

Ranking algorithm:

1. Learned shortcuts first - Items where you've used that exact search term before rank highest
2. Frecency decides ties - Among learned shortcuts, most frequently/recently used wins
3. Fuzzy matches last - Items that match but you haven't searched that way before

This means an item you use 10 times with "ff" will beat a command named "ff" that you've never executed.

What's tracked:

• Apps, actions, workflows, quicklinks
• URLs, workflow executions (wallpaper changes, file opens, etc.)
• Each item stores up to 5 recent search terms

Example:

Type "ff" → select Firefox → "ff" recorded
Type "ff" → select Firefox → frecency increased
Type "ff" → Firefox is now first (beats other "ff" matches you never use)

Type "wl" → select "Set wallpaper: sunset.jpg" → "wl" recorded
Type "wl" → wallpaper action appears first

Terms naturally age out based on frecency, so your shortcuts stay relevant as habits change.

When you open Hamr with an empty search, you may see suggested apps at the top marked with a sparkle icon. These combine your usage frequency with contextual predictions.

What triggers suggestions:

How it works:

1. Every app launch records context (time, workspace, monitor, previous app)
2. Patterns are detected using Wilson score intervals (statistically sound for small samples)
3. Context signals combine with frecency (frequency + recency) into a final score
4. Apps above 25% confidence appear as suggestions (max 2)

No configuration needed. Suggestions appear automatically as patterns emerge. Use Hamr normally and it learns your habits within a few days.

Hamr is configured via ~/.config/hamr/config.json. Use the built-in settings plugin (/settings) to browse and modify options - no manual editing needed.

The action bar shortcuts are fully customizable. Edit ~/.config/hamr/config.json to change which prefixes appear and which plugins they trigger:

{
  "search": {
    "actionBarHints": [
      { "prefix": "~", "icon": "folder", "label": "Files", "plugin": "files" },
      { "prefix": ";", "icon": "content_paste", "label": "Clipboard", "plugin": "clipboard" },
      { "prefix": "/", "icon": "extension", "label": "Plugins", "plugin": "action" },
      { "prefix": "!", "icon": "terminal", "label": "Shell", "plugin": "shell" },
      { "prefix": "=", "icon": "calculate", "label": "Math", "plugin": "calculate" },
      { "prefix": ":", "icon": "emoji_emotions", "label": "Emoji", "plugin": "emoji" }
    ]
  }
}

Each hint has:

• prefix: The trigger character (e.g., ~, ;, :)
• icon: Material Symbol name
• label: Display name shown in the action bar
• plugin: Plugin ID to launch (e.g., files, clipboard, emoji) or action for plugin search mode

You can reorder, remove, or add hints. For example, to replace emoji with notes:

{ "prefix": ":", "icon": "note", "label": "Notes", "plugin": "notes" }

~/.config/quickshell/hamr/       # Symlink to cloned repo
├── shell.qml                    # Entry point
├── GlobalStates.qml             # UI state
├── plugins/                     # Built-in plugins (read-only)
├── modules/
│   ├── common/                  # Appearance, Config, widgets
│   ├── launcher/                # Launcher UI components
│   └── imageBrowser/            # Image browser UI
├── services/                    # LauncherSearch, PluginRunner, etc.
└── scripts/                     # Thumbnail generation, OCR indexing

~/.config/hamr/
├── plugins/                     # User plugins (override built-in)
├── config.json                  # User configuration
├── quicklinks.json              # Custom quicklinks
└── search-history.json          # Search history (auto-generated)

Launchers like Vicinae aim for Raycast extension compatibility, but this approach has limitations on Linux:

• macOS-hardcoded paths - Many Raycast extensions use paths like ~/Library/... that don't exist on Linux (example issue)
• macOS APIs - Extensions often rely on macOS-specific APIs (AppleScript, Finder, Keychain)
• Heavy runtime - Requires Node.js + TypeScript toolchain for plugins

Hamr takes a different approach: plugins are native Linux scripts using a simple JSON protocol. Write in any language, use Linux-native tools (fd, fzf, wl-copy), and integrate with your existing dotfiles.

# A complete Hamr plugin - no SDK, no build step
#!/usr/bin/env python3
import json, sys
print(json.dumps({"type": "results", "results": [{"id": "1", "name": "Hello"}]}))

This means browser bookmarks on Linux just read from ~/.config/google-chrome/Default/Bookmarks directly - no compatibility layer needed.

Want functionality from a Raycast extension? Use the built-in create-plugin workflow:

/create-plugin
> Replicate this Raycast extension: https://github.com/raycast/extensions/tree/main/extensions/browser-bookmarks

The AI will analyze the Raycast extension, translate the patterns to Hamr's protocol, and create a native Linux plugin. See plugins/AGENTS.md for the full conversion guide.

Hamr is fully local and offline. No data ever leaves your machine.

What's tracked for smart suggestions:

• App launch counts and timestamps
• Time of day / day of week patterns
• Workspace and monitor associations
• App sequence patterns (which app follows another)

What's NOT tracked:

• No network requests, analytics, or telemetry
• No file contents or document text
• No keystrokes or input outside Hamr
• No data shared with plugins (they only receive search queries)

To clear all history: rm ~/.config/hamr/search-history.json

Hamr is extracted and adapted from end-4's illogical-impulse. Major thanks to end-4 for the Material Design theming, fuzzy search, widget components, and overall architecture.

Hamr is fully standalone and works out of the box on any Hyprland setup. It optionally integrates with illogical-impulse for enhanced theming features if detected.

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

Hamr is a derivative work based on end-4/dots-hyprland, which is also licensed under GPL-3.0. Major thanks to end-4 for the Material Design theming, fuzzy search, widget components, and overall architecture that made this project possible.

See the LICENSE file for the full license text.