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

paru -S hamr

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

Supported Compositors: Hyprland, Niri

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)
• Live plugin updates - Plugins can emit real-time updates via daemon mode (no full list refresh, preserves focus)
• File watching - Plugins can watch files/directories for changes with native inotify

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.

The niri plugin provides natural language access to Niri window management, optimized for Niri's scrollable tiling layout.

Window Management:

• close window, fullscreen, toggle floating, center column
• maximize column, toggle tabbed (column tabbed display)

Column Operations:

• consume window - Add window to the right into the focused column
• expel window - Move focused window out of column
• expand column - Expand column to available width
• focus column left/right, move column left/right

Window Movement:

• focus window up/down, move window up/down
• swap window left/right

Workspace Navigation:

• focus workspace up/down, focus workspace previous
• move window to workspace up/down
• move column to workspace up/down

Monitor Control:

• focus monitor left/right/up/down/next/previous
• move window to monitor left/right
• move column to monitor left/right

Utilities:

• toggle overview, screenshot, screenshot window, screenshot screen
• show hotkey overlay, switch keyboard layout
• power off monitors, power on monitors

Type /niri to browse all available actions, or search directly from the main bar.

A Rust-based rewrite is available in public alpha. It offers the same features with improved performance and a more streamlined codebase.

Try it out:

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

This will install the Rust version instead of the QML version. The alpha version is stable for daily use but may have some rough edges.

Requirements: Linux with a supported Wayland compositor (Hyprland or Niri)

# 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 libpulse jq libqalculate \
    ttf-material-symbols-variable ttf-jetbrains-mono-nerd ttf-readex-pro

# Plus your compositor (one of):
paru -S hyprland  # or
paru -S niri

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

# Try without installing
nix run github:Stewart86/hamr -- --help

# Install to your profile
nix profile install github:Stewart86/hamr

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hamr.url = "github:Stewart86/hamr";
  };

  outputs = { self, nixpkgs, hamr, ... }: {
    # NixOS configuration
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        {
          nixpkgs.overlays = [ hamr.overlays.default ];
          environment.systemPackages = [ pkgs.hamr ];
        }
      ];
    };

    # Or with Home Manager
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      modules = [
        {
          nixpkgs.overlays = [ hamr.overlays.default ];
          home.packages = [ pkgs.hamr ];
        }
      ];
    };
  };
}

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

Hamr starts hidden and listens for a toggle signal. Configure your compositor to toggle Hamr with a keybinding.

# Autostart hamr
exec-once = hamr

# Toggle Hamr with Super key (tap to toggle)
bind = SUPER, SUPER_L, global, quickshell:hamrToggle
bindr = SUPER, SUPER_L, global, quickshell:hamrToggleRelease

# Or toggle with Ctrl+Space
bind = Ctrl, Space, global, quickshell:hamrToggle

systemctl --user enable hamr.service
systemctl --user add-wants niri.service hamr.service
systemctl --user start hamr.service

binds {
    // Toggle Hamr with Ctrl+Space
    Ctrl+Space { spawn "hamr" "toggle"; }

    // Or with Mod+Space (Super key)
    Mod+Space { spawn "hamr" "toggle"; }
}

spawn-at-startup "hamr"

Start Hamr manually (for testing):

hamr

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

You can bind keys to open specific plugins directly:

hamr plugin <plugin_name>

# Open clipboard directly with Mod+V
bind = SUPER, V, exec, hamr plugin clipboard

# Open emoji picker with Mod+Period
bind = SUPER, Period, exec, hamr plugin emoji

# Open file search with Mod+E
bind = SUPER, E, exec, hamr plugin files

binds {
    // Open clipboard directly with Mod+V
    Mod+V { spawn "hamr" "plugin" "clipboard"; }

    // Open emoji picker with Mod+Period
    Mod+Period { spawn "hamr" "plugin" "emoji"; }

    // Open file search with Mod+E
    Mod+E { spawn "hamr" "plugin" "files"; }
}

Available plugins: apps, bitwarden, calculate, clipboard, emoji, files, notes, pictures, power, quicklinks, screenshot, settings, shell, snippet, todo, wallpaper, hyprland, niri, etc.

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: Quickshell was built against Qt 6.10.0 but the system has updated to Qt 6.10.1...

paru -S quickshell --rebuild
# or for quickshell-git:
paru -S quickshell-git --rebuild

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

# Install matugen (Arch)
paru -S matugen-bin

# Set a wallpaper - colors are generated automatically
# Type /wallpaper in Hamr

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 a folder containing:

• manifest.json - Plugin metadata and configuration
• handler.py (optional) - Handler script for dynamic plugins

For simple actions, use staticIndex in the manifest - no handler needed.

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

Full documentation: See plugins/README.md for the complete protocol reference, response types, indexing, daemon mode, forms, and more.

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": "update",
  "items": [
    {
      "id": "item-1",
      "gauge": {"value": 75, "max": 100},
      "badges": [{"text": "5"}]
    }
  ]
}

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

{
  "type": "execute",
  "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": "gridBrowser",
  "gridBrowser": {
    "title": "Select Emoji",
    "items": [
      {"id": "😀", "name": "grinning face", "icon": "😀", "iconType": "text", "keywords": ["happy"]}
    ],
    "columns": 10,
    "cellAspectRatio": 1.0,
    "actions": [{"id": "copy", "name": "Copy", "icon": "content_copy"}]
  }
}

{
  "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": "My Plugin",
  "daemon": {
    "enabled": true,
    "background": false
  }
}

# Emit update to individual items without full list refresh
emit({"type": "update", "items": [{"id": "volume", "gauge": {"value": 75, "max": 100}}]})

# Emit status update for plugin badge in main list
emit({"type": "status", "status": {"badges": [{"text": "5"}]}})

# Emit incremental index update (adds items to search)
emit({"type": "index", "mode": "incremental", "items": [{"id": "new-item", "name": "..."}]})

{
  "name": "Screenshot",
  "description": "Capture screen region",
  "icon": "screenshot",
  "staticIndex": [
    {
      "id": "snip",
      "name": "Screenshot Snip",
      "description": "Capture and copy screen region",
      "icon": "screenshot",
      "keywords": ["screenshot", "capture", "snip"],
      "execute": {
        "command": ["bash", "-c", "grim -g \"$(slurp)\" - | wl-copy"],
        "notify": "Screenshot copied",
        "close": true
      }
    }
  ]
}

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
└── plugin-indexes.json          # Plugin data and frecency (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/plugin-indexes.json

Hamr was originally 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 that inspired this project.

Hamr is now fully standalone and works out of the box on any supported Wayland compositor (Hyprland, Niri).

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.