A comprihensive walker guide for omarchy

[nskrdev]

Walker Documentation

Overview

Walker is a powerful application launcher and search tool with prefix-based functionality that allows quick access to different search modes and actions.

Note: This documentation describes Omarchy's customized Walker configuration with the omarchy-default theme. All prefix mappings and keybindings are specific to Omarchy's setup.

Why This Documentation Exists

I was wondering if there was a universal file search feature in Omarchy (like Spotlight on Mac) and discovered that Walker already has this capability! After experimenting with different prefixes, I found that Omarchy actually has several powerful search modes built-in. Since there was no documentation explaining these features, I explored the configuration and tested each prefix to understand what they do. This guide documents everything I discovered, hoping it will be helpful for others who want to unlock Walker's full potential in Omarchy.

---

How to Launch Walker

Walker can be launched in several ways:

Default Keybindings

• Super + Space - Launch Walker (main app launcher)
• Super + Ctrl + E - Launch Walker in symbols mode (emoji picker)
• Super + K - View all keybindings using Walker

Command Line

# Launch Walker normally
omarchy-launch-walker

# Launch in dmenu mode (for scripts)
walker --dmenu -p "enter text...."

# Launch with specific mode
omarchy-launch-walker -m symbols

---

Default Search (No Prefix)

When you open Walker without any prefix, it searches across:

• Desktop applications
• Menus
• Web search (automatic fallback)

How it works:

• Type an application name to launch it
• If no application matches, Walker automatically offers to search the web with Google
• Simply press Return to open the search in your default browser

Desktop Applications Actions

• Return - Launch application
• Shift + Return - Launch application and keep Walker open
• Ctrl + H - Clear search history
• Ctrl + P - Pin/unpin application
• Ctrl + N - Move pinned item up
• Ctrl + M - Move pinned item down

Try it now:

1. Press Super + Space to open Walker
2. Start typing an application name (e.g., "firefox")
3. Press Return to launch
4. Or type something random (e.g., "weather today") and press Return to search the web

---

Prefix-Based Search Modes

. Files and Folders

Search for files and folders by name in your filesystem.

Search Scope: File search is limited to your home directory (~) and does not search the entire root (/) filesystem. This keeps searches fast and focused on your personal files.

Hidden Files: By default, hidden files (those starting with .) may not be included in search results. The file search typically shows visible files and folders only.

Actions:

• Return - Open file/folder
• Ctrl + Return - Open directory containing the file
• Ctrl + Shift + C - Copy file path to clipboard
• Ctrl + C - Copy file to clipboard

Try it now:

1. Press Super + Space to open Walker
2. Type .Documents to navigate to your Documents folder
3. Type .photo to search for files with "photo" in the name
4. Navigate with arrow keys and press Return to open

---

: Emoji/Symbols

Search for symbols (code symbols, special characters, emojis, etc.).

Actions:

• Return - Select and insert symbol
• Ctrl + H - Clear search history

Quick Access:

• Press Super + Ctrl + E to launch Walker directly in symbols mode (emoji picker)

Try it now:

1. Press Super + Ctrl + E for quick emoji access
2. Or press Super + Space and type :heart to search for heart emoji
3. Press Return to copy the symbol to clipboard

---

= Calculator

Perform mathematical calculations directly in Walker.

Actions:

• Return - Copy result to clipboard
• Ctrl + D - Delete selected calculation from history
• Ctrl + S - Save calculation to history

Example:

=2+2
=sqrt(16)
=100*0.15
=pi*10^2

Try it now:

1. Press Super + Space to open Walker
2. Type =50*1.08 to calculate with tax
3. Press Return to copy the result

Managing Calculator History:

To delete individual calculations from history:

1. Open Walker and type = to see your calculation history
2. Use arrow keys to navigate to the calculation you want to remove
3. Press Ctrl + D to delete that specific entry
4. The list will refresh automatically

Note: If you encounter an error about qalculate config, create the directory:

mkdir -p ~/.config/qalculate
touch ~/.config/qalculate/qalc.cfg

---

$ Clipboard History

Access and manage your clipboard history.

Actions:

• Return - Copy selected item to clipboard
• Ctrl + D - Remove item from history
• Ctrl + Shift + D - Clear all clipboard history
• Ctrl + I - Toggle image display
• Ctrl + O - Edit clipboard item

Try it now:

1. Copy a few different things to your clipboard
2. Press Super + Space and type $
3. Browse your clipboard history and press Return to re-copy an item

---

Integration with Omarchy

Walker is deeply integrated into Omarchy's workflow:

System Menus

• Super + Alt + Space - Omarchy main menu (uses Walker)
• Super + Escape - Power menu
• Super + K - Keybindings viewer (uses Walker)

Automatic Restarts

Walker automatically restarts when you:

• Change fonts (omarchy-font-set)
• Update Walker configuration
• Refresh Omarchy configs

Backend Service

Walker works with the Elephant service which provides:

• Calculator functionality
• Desktop applications indexing
• File search capabilities
• And more

---

Tips & Tricks

1. Quick Navigation: Use prefix shortcuts to jump directly to the search mode you need
2. Fuzzy Search: By default, Walker uses fuzzy matching - you don't need to type exact names
3. History Management: Most providers maintain search history - use Ctrl + D to delete individual items or Ctrl + H to clear all history (where supported)
4. Pinning: Pin frequently used applications for instant access
5. Clipboard Management: Use $ to access your clipboard history and never lose copied content
6. File Search Shortcut: In Omarchy, . quickly searches files in your home directory - faster than using a file manager
7. Exact Search: Prefix your query with ' when you need exact matching instead of fuzzy search
8. Calculator on the Fly: Use = for quick calculations without opening a calculator app
9. Emoji Picker: Press Super + Ctrl + E for instant emoji/symbol access
10. Web Search Fallback: Don't know a command? Just type what you want to search and Walker will offer to search the web automatically
11. Keep Walker Open: Use Shift + Return when launching apps to keep Walker open for multiple launches
12. Scripting with Walker: Use walker --dmenu in your scripts for interactive selections

---

Troubleshooting

Walker doesn't open

• Check your Hyprland keybindings configuration
• Run walker from terminal to test if it launches
• Verify the walker service is running: pgrep -f "walker --gapplication-service"
• Restart the service: omarchy-restart-walker

Prefix not working

• Make sure you're typing the prefix first (e.g., .Documents not Documents.)
• Check config/walker/config.toml to verify prefix mappings
• Ensure Elephant service is running: pgrep elephant

No search results

• Try toggling exact search off with Ctrl + E
• Clear search history with Ctrl + H
• Check if the provider is enabled in the configuration
• Restart Walker: omarchy-restart-walker

Calculator shows qalculate error

• Create the qalculate config directory:

  mkdir -p ~/.config/qalculate
  touch ~/.config/qalculate/qalc.cfg

Walker is slow or unresponsive

• Restart the Walker service: omarchy-restart-walker
• Check if Elephant is running: pgrep elephant
• Reduce max_results in config if you have many applications

---

Related Tools

• omarchy-menu: System menu powered by Walker
• omarchy-menu-keybindings: View all Hyprland keybindings in Walker
• omarchy-launch-walker: Script to launch Walker with proper settings
• omarchy-restart-walker: Restart Walker and Elephant services
• Hyprland: Window manager that Walker integrates with
• Elephant: Backend service that powers Walker providers

---

I hope this documentation helps someone! 😇

[kmf]

Thanks for this Comprehensive guide!

[pbakiewicz]

Thanks @nskrdev for great manual.

I have a question:

Is it possible to change walker different application launcher behavior to NOT spawn new instance if application is already running but simply switch focus to it?

That would be a massive boost to efficiently stitching between apps.

[pbakiewicz]

I understand what you mean, but it could be done with simple shortcut for forcing app launching like SHIFT + return.

I found that windows switching by fuzzy finding app name is so useful to me that I would do that all day long. Don't think so it is possible right now out-of-the box in omarchy.

[abenz1267]

thats what elephant-windows is for.

[abenz1267]

i've actually just added this:

[pbakiewicz]

Thanks @abenz1267 . I agree - this functionality should be included in the main package since it is so extremely useful.

Again, thanks for you quick replies.

[siayu18]

I think adding another symbol for finding running windows only would be great. Or having additional entries in the menu that differentiates (e.g., switch to tab ->) between running windows of an app and opening a new one.

[HegewaldK]

There is also a documentation currently under development: https://walkerlauncher.com/
This is the github site: https://github.com/mah3uz/wlaker-docs

Unfortunately Omarchy changed almost all default Walker shortcuts to something else. 🫤

[abenz1267]

this is not official though.

[ry10hu]

Is there any way to change the Google shortcut to something else? (Eg DDG with firefox)

[erickueen]

Create a new file in ~/.config/elephant/websearch.toml
For DDG for example:

[[entries]]
default = true
name = "DuckDuckGo"
url = "https://duckduckgo.com/?q=%TERM%"

It will open on fireforx if you previously set it as your default browser.

(You need to restart your session or run omarchy-restart-walker after creating the config file)

[ewhd]

I have a question that maybe someone here can comment on:

This doc describes a set of "Desktop Applications Actions", specifically the 3 related to pinning items in the walker menu:

• Ctrl + P - Pin/unpin application
• Ctrl + N - Move pinned item up
• Ctrl + M - Move pinned item down

I cannot for the life of me find /where/ these are set, or how to change them (I would like to use Ctrl + N/P for up and down selections, to conform to my muscle memory from emacs).

Anyone have anything useful to suggest?

[erickueen]

At the end of ~/.config/walker/config.toml, in this example I'm rebinding pin and unpin to "ctrl l"

[providers.actions]
desktopapplications = [
  {action= "pin", bind="ctrl l", after="AsyncReload"},
  {action= "unpin", bind="ctrl l", after="AsyncReload"}
]

After that run omarchy-restart-walker

More config options here: https://walkerlauncher.com/docs/configuration
And the default config is here: https://github.com/abenz1267/walker/blob/master/resources/config.toml#L131

[ewhd]

Thank you! I clearly should have grepped the default config.toml.

For anyone curious, my final config includes:

[keybinds]
quick_activate = []
close = ["Escape", "ctrl g"]
next = ["Down", "ctrl n"]
previous = ["Up", "ctrl p"]

[providers.actions]
desktopapplications = [
  { action = "pin", bind = "ctrl b", after = "AsyncReload" },
  { action = "unpin", bind = "ctrl u", after = "AsyncReload" },
  { action = "pinup", bind = "ctrl Up", after = "AsyncReload" },
  { action = "pindown", bind = "ctrl Down", after = "AsyncReload" }
]

[logxdx]

I want to create a wallpaper switcher menu using walker.
I was trying using this script.

#!/bin/bash

# Directory containing wallpapers
WALL_DIR="$HOME/Wallpapers"
CURRENT_BACKGROUND_LINK="$HOME/.config/omarchy/current/background"

# Current directory (to cd back to)
CWD="$(pwd)"

cd "$WALL_DIR" || exit

# Handle spaces in filenames
IFS=$'\n'

# Grab the user-selected wallpaper
SELECTED_WALL=$WALL_DIR/$(for a in *.jpg *.png *.jpeg; do
    echo -en "$a\0icon\x1f$a\n"
done | walker --dmenu)

if [ -n "$SELECTED_WALL" ]; then
    ln -nsf "$SELECTED_WALL" "$CURRENT_BACKGROUND_LINK"
    matugen image "$SELECTED_WALL"
fi

# Go back to where you came from
cd "$CWD" || exit

I get the names of the available wallpapers but I can't see the image preview like the one available when searching for files using the prefix:

Any way this can be done?

[abenz1267]

you probl. wanna have a look at this: https://benz.gitbook.io/walker/customization/custom-menus

[Erehr]

How can I enable bookmarks search?

[[providers.prefixes]]
prefix = "%"
provider = "bookmarks"

Added this to walker config.toml but it did nothing. Both elephant listproviders and omarchy-restart-walker don't show bookmarks provider loaded either. Looking further elephant-bookmarks doesn't seem to be included in omarchty-walker at all.

Installing elephant-bookmarks manually with aur results in
ERROR providers load=/etc/xdg/elephant/providers/[bookmarks.so](http://bookmarks.so/) err="plugin.Open(\"/etc/xdg/elephant/providers/bookmarks\"): plugin was built with a different version of package [github.com/abenz1267/elephant/v2/pkg/common](http://github.com/abenz1267/elephant/v2/pkg/common)"

Meanwhile elephant-windows provider installed the same way works flawlessly.

[kmf]

@Erehr how did you install the elephant-windows provider?

[abenz1267]

elephant and the providers need to be installed from the same source. A version mismatch leads to the error you are seeing.

[kmf]

I have an open issue to include more elephant providers packages.

I've added elephant-bookmarks

Related Link: omacom-io/omarchy-pkgs#12

[Erehr]

@kmf At first installed both elephant-windows and elephant-bookmarks through install > AUR menu. Windows worked fine.

elephant and the providers need to be installed from the same source. A version mismatch leads to the error you are seeing.

That's how I finally managed to get it working by installing elephant-all which removed all elephant packages and installed elephant + every avaliable provider together.

[SadmanAnubhob]

I have been using omarchy only for a week (also linux) can someone help me to change my walker's design like adding shadows, rounded corners and all that without changing the omarchy default files

[pelephant2]

Ctrl+Shift+D clears all clipboard history. Is there an equivalent command I can run from my terminal to clear the clipboard history? I want to schedule a cron job every 5 minutes (with whatever this command might be) to clear the clipboard history. It appears there's no setting to disable this feature.

[abenz1267]

read elephant generatedoc clipboard

[pelephant2]

The easiest way to disable Omarchy clipboard history (via elephant) is with the following:

mkdir -p ~/.config/elephant
echo "max_items = 0" > ~/.config/elephant/clipboard.toml

and that's assuming you don't have a ~/.config/elephant/clipboard.toml file which I did not.

Or for a 1 minute history of clipboard items you can use auto_cleanup = 1 in place of max_items = 0 above, which will store any copied item in the clipboard for 1 minute then delete it (I think).

[abenz1267]

the easiest way to disable it is either uninstall elephant-clipboard or add clipboard to ignored_providers in elephant.toml.

[sedubois]

Thanks @nskrdev for this great resource. I haven't yet figured out how to add custom entries such as international characters to the emoji picker menu, would you have an idea? Using Omarchy 3.2.0. I ran elephant generatedoc symbols but its output doesn't help me understand what I should precisely do (how to format the whole ~/.config/elephant/symbols.toml, also when adding several custom symbols):

2025/11/24 08:59:00 INFO elephant config="using default config"
### Elephant Symbols

Search for emojis and symbols

#### Requirements

- `wl-clipboard`


#### Possible locales
af,ak,am,ar,ar_SA,as,ast,az,be,bew,bg,bgn,blo,bn,br,bs,ca,ca_ES,ca_ES_VALENCIA,ccp,ceb,chr,ckb,cs,cv,cy,da,de,de_CH,doi,dsb,el,en,en_001,en_AU,en_CA,en_GB,en_IN,es,es_419,es_MX,es_US,et,eu,fa,ff,ff_Adlm,fi,fil,fo,fr,fr_CA,frr,ga,gd,gl,gu,ha,ha_NE,he,hi,hi_Latn,hr,hsb,hu,hy,ia,id,ig,is,it,ja,jv,ka,kab,kk,kk_Arab,kl,km,kn,ko,kok,ku,ky,lb,lij,lo,lt,lv,mai,mi,mk,ml,mn,mni,mr,ms,mt,my,ne,nl,nn,no,nso,oc,om,or,pa,pa_Arab,pap,pcm,pl,ps,pt,pt_PT,qu,quc,rhg,rm,ro,root,ru,rw,sa,sat,sc,sd,si,sk,sl,so,sq,sr,sr_Cyrl,sr_Cyrl_BA,sr_Latn,sr_Latn_BA,su,sv,sw,sw_KE,ta,te,tg,th,ti,tk,tn,to,tr,tt,ug,uk,ur,uz,vec,vi,wo,xh,yo,yo_BJ,yue,yue_Hans,zh,zh_Hant,zh_Hant_HK,zu,

`~/.config/elephant/symbols.toml`
#### Config
| Field | Type | Default | Description |
| --- | ---- | ---- | --- |
|icon|string|depends on provider|icon for provider|
|name_pretty|string|depends on provider|displayed name for the provider|
|min_score|int32|depends on provider|minimum score for items to be displayed|
|hide_from_providerlist|bool|false|hides a provider from the providerlist provider. provider provider.|
|locale|string|en|locale to use for symbols|
|history|bool|true|make use of history for sorting|
|history_when_empty|bool|false|consider history when query is empty|
|command|string|wl-copy|default command to be executed. supports %VALUE%.|

Also, how to make sure the config file is taken into account after having created or modified it?

BTW where are we supposed to be viewing this documentation in a more readable format (it appears meant to be rendered as a table)?

[abenz1267]

yeah.. i mean... no offense but you need to learn how to read. elephant generatedoc literally tells you the config file is ~/.config/elephant/<provider>.toml 😂

[sedubois]

@abenz1267 The above configuration was added to Omarchy's ~/.config/walker/config.toml as, unlike the path you mentioned, that file is the one pre-configured by Omarchy and already contains numerous other providers. Even the symbols provider is in there, which is the closest to what we're trying to add here with these unicode characters. For reference, you can see here what it looks like: https://github.com/basecamp/omarchy/blob/master/config/walker/config.toml

One might be excused to think that if other providers need to be configured in ~/.config/elephant/<provider>.toml, then it must be the same for the unicode one. ~/.config/walker/config.toml was also referenced above by @nskrdev as the one to be used.

The confusion comes from the fact that configuration is needed in both of those files (see next comment).

[sedubois]

At any rate, I can confirm the below config provides a functional unicode character picker 🎉:

• Install the elephant Unicode provider with yay -S elephant-unicode

• Install wtype with sudo pacman -S wtype

• Append to ~/.config/walker/config.toml:

[[providers.prefixes]]
prefix = "u"
provider = "unicode"

• Create ~/.config/elephant/unicode.toml:

history = true
history_when_empty = true
command = "wtype %VALUE%" 

• Append to ~/.config/hypr/bindings.conf:

 bindd = SUPER SHIFT, U, Unicode Characters, exec, omarchy-launch-walker -m unicode

• omarchy-restart-walker

Now, I can open the unicode picker with super-shift-U, search for a character e.g. with "l stroke", type enter, and it will be typed to the application. If I reopen the application, that character appears first in the list, which makes it easier to select it again.

Thanks a lot @abenz1267 and @nskrdev for your help.

[abenz1267]

You don't need to add a prefix if you only intent to use it directly via the keybind.

[sedubois]

@abenz1267 yes, I'll see which system I prefer, now I can access it both ways indeed:

• super-shift-U
• super-space u