Configuration¶

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

Configuration Reference¶

Category	Option	Default	Description
Apps	`terminal`	(auto-detected)	Terminal emulator for shell commands
	`fileManager`	(auto-detected)	File manager for file operations
	`browser`	(auto-detected)	Web browser for URL opening
Search	`maxDisplayedResults`	`16`	Maximum results shown in launcher
	`maxRecentItems`	`20`	Recent history items on empty search
	`maxResultsPerPlugin`	`0`	Hard limit per plugin (0 = no limit)
	`pluginDebounceMs`	`150`	Search input debounce (ms)
	`diversityDecay`	`0.7`	Decay for consecutive results from same plugin (0-1, lower = more diverse)
	`engineBaseUrl`	`https://www.google.com/search?q=`	Default search engine URL
	`excludedSites`	`[]`	Sites to exclude from web search results
	`pluginRankingBonus`	`{}`	Per-plugin score boosts (e.g., `{"apps": 200}`)
Action Bar	`actionBarHints`	see below	Customizable action bar shortcuts

Prefix Shortcuts¶

Search prefixes let you quickly jump to specific functionality by typing a character:

Prefix	Option	Function
`/`	`plugins`	Search plugins by name
`@`	`app`	Application search
`:`	`emojis`	Emoji search
`=`	`math`	Calculator
`!`	`shellCommand`	Shell command
`?`	`webSearch`	Web search

Configure these in config.json under the search section:

{
  "search": {
    "plugins": "/",
    "app": "@",
    "emojis": ":",
    "math": "=",
    "shellCommand": "!",
    "webSearch": "?"
  }
}

Plugin Ranking Bonus¶

Control which plugins appear higher in search results by assigning bonus points. This is useful when you want certain plugins (like apps) to consistently rank above others.

How It Works¶

Hamr calculates a composite score for each result based on: - Fuzzy match score (0-1000+): How well the query matches the item name - Frecency (0-300): Usage frequency combined with recency - History boost (+200): When query exactly matches a previously used search term - Plugin ranking bonus: Your custom per-plugin boost

Higher total scores appear first in results.

Configuration¶

Add pluginRankingBonus to your config.json:

{
  "search": {
    "pluginRankingBonus": {
      "apps": 200,
      "settings": 100,
      "files": 50
    }
  }
}

Finding Plugin IDs¶

To find the ID of a plugin: 1. Type / in Hamr to open the plugin list 2. The plugin ID is shown in the result subtitle (e.g., "apps", "clipboard", "emoji")

Or check the id field in the plugin's manifest.json.

Recommended Values¶

Bonus Range	Effect
50-100	Subtle boost, breaks ties in favor of this plugin
150-250	Noticeable preference, plugin results appear higher
300+	Strong preference, almost always appears first

Example use cases: - "apps": 200 - Prioritize launching applications over other results - "clipboard": 100 - Boost clipboard items when searching for copied text - "quicklinks": 150 - Make your custom quicklinks more prominent

Interaction with Diversity Decay¶

The diversityDecay setting (default: 0.7) penalizes consecutive results from the same plugin. Even with a high bonus, the 2nd result from a plugin scores 70% of the first, the 3rd scores 49%, etc. This prevents one plugin from dominating all results.

Action Bar Hints¶

The action bar shortcuts are fully customizable via actionBarHints. Default hints include:

{
  "search": {
    "actionBarHints": [
      { "prefix": "~", "icon": "folder_open", "label": "Files", "plugin": "files" },
      { "prefix": ";", "icon": "content_paste", "label": "Clipboard", "plugin": "clipboard" },
      { "prefix": "=", "icon": "calculate", "label": "Calculate", "plugin": "calculate" },
      { "prefix": ":", "icon": "emoji_emotions", "label": "Emoji", "plugin": "emoji" },
      { "prefix": "!", "icon": "terminal", "label": "Shell", "plugin": "shell" }
    ]
  }
}

Each hint has:

prefix: The trigger character (e.g., ~, ;, :)
icon: Icon name (GTK-compatible icon names)
label: Display name shown in the action bar
plugin: Plugin ID to launch
description: Optional description (shown in settings)

Direct Plugin Keybindings¶

You can bind keys to open specific plugins directly:

hamr plugin <plugin_name>

Hyprland¶

# ~/.config/hypr/hyprland.conf

# 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

Niri¶

// ~/.config/niri/config.kdl
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"; }
}

Sway¶

# ~/.config/sway/config

# Open clipboard directly with Mod+V
bindsym $mod+V exec hamr plugin clipboard

# Open emoji picker with Mod+Period
bindsym $mod+Period exec hamr plugin emoji

# Open file search with Mod+E
bindsym $mod+E exec hamr plugin files

File Structure¶

~/.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)

~/.local/share/hamr/             # Installation directory (AUR/manual)
├── plugins/                     # Built-in plugins (read-only)
└── daemon                       # Hamr daemon binary

Troubleshooting¶

"I ran `hamr` but nothing appears"¶

This is expected. Hamr starts hidden and waits for a toggle signal. Make sure you:

Added the keybinding to your compositor config (see Installation)
Reloaded your compositor config
Press your keybind (e.g., Super key or Ctrl+Space)

Check daemon status¶

# Check if daemon is running
hamr status

# View daemon logs
tail -f /tmp/hamr-daemon.log

View logs¶

Hamr writes debug logs to /tmp/ with symlinks to the latest: - Daemon: /tmp/hamr-daemon.log - TUI: /tmp/hamr-tui.log - GTK: /tmp/hamr-gtk.log

# Follow daemon logs in real-time
tail -f /tmp/hamr-daemon.log

# View recent entries from both
tail -n 100 /tmp/hamr-daemon.log /tmp/hamr-tui.log

# Search for specific patterns
grep -i "error\|warn" /tmp/hamr-daemon.log

Configuration issues¶

If your config isn't working:

Check JSON syntax: python -m json.tool ~/.config/hamr/config.json
Verify daemon picks up changes: hamr daemon-reload
Check for unknown fields in logs: grep "unknown field" /tmp/hamr-daemon.log

Plugin not responding¶

# Check if plugin is connected
grep "plugin" /tmp/hamr-daemon.log | tail -20

# Look for action forwarding issues
grep "handle_item_selected\|Forwarding action" /tmp/hamr-daemon.log

Warning about missing `colors.json`¶

This is harmless. Hamr uses built-in default colors. For dynamic theming from your wallpaper, install matugen and use the wallpaper plugin.

Warning about missing `quicklinks.json`¶

This is harmless. Quicklinks are optional. To add quicklinks, create ~/.config/hamr/quicklinks.json:

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

Configuration¶

Configuration Reference¶

Prefix Shortcuts¶

Plugin Ranking Bonus¶

How It Works¶

Configuration¶

Finding Plugin IDs¶

Recommended Values¶

Interaction with Diversity Decay¶

Action Bar Hints¶

Direct Plugin Keybindings¶

Hyprland¶

Niri¶

Sway¶

File Structure¶

Troubleshooting¶

"I ran hamr but nothing appears"¶

Check daemon status¶

View logs¶

Configuration issues¶

Plugin not responding¶

Warning about missing colors.json¶

Warning about missing quicklinks.json¶

"I ran `hamr` but nothing appears"¶

Warning about missing `colors.json`¶

Warning about missing `quicklinks.json`¶