It runs as a plugin inside the omarchy-shell process you already have, so there is no separate launcher to start. Press AltSpace, type, and every source answers in one ranked list: apps, open windows, Omarchy commands and toggles, files, clipboard history, calculations and conversions, reminders, calendar events, system views such as open ports, and the web. Search runs on your machine. Web suggestions stay off until you turn them on, and currency conversions fetch a rate that sends only the two currency codes (see Privacy and security).

Install

omarchy plugin add https://github.com/maajix/omarchy-spotlight.git --enable

Then press AltSpace. Installation covers requirements, the first run, updating and removing. New to Spotlight? Take the Quickstart, then read How search works.

What's new in 1.6.2

• Change Theme and Change Background now apply the choice you pick.
• Change Font now opens Omarchy's font picker.

Every release is listed in the Changelog.

Features

Reference

Resources

Requirements

You need Omarchy 4 (Quattro), the release Spotlight targets. Spotlight uses only tools that ship with stock Omarchy:

Install

1. Add the plugin

   omarchy plugin add https://github.com/maajix/omarchy-spotlight.git --enable

   Omarchy warns that plugins run as arbitrary, unsandboxed code inside the omarchy-shell process and asks you to confirm. It then clones the repository to ~/.config/omarchy/plugins/io.github.maajix.spotlight, validates it and, because of --enable, turns it on. Add --yes to skip the prompts. Spotlight is also listed in the Omarchy Plugin Marketplace.

2. Get the shortcut

   As soon as the plugin loads, Spotlight binds AltSpace, which is free on stock Omarchy. It writes one marked block to ~/.config/hypr/bindings.lua and reloads Hyprland. You do not need to edit anything. If AltSpace is already taken, Spotlight leaves it alone and the setup tour asks you to pick another combination.

3. Open Spotlight

   Press AltSpace. On the first open, the setup tour appears: a welcome, the shortcut, what Spotlight should search, and a few things to try. Press Enter to move on, or Esc (Skip tour) to keep the defaults. Skipping does not undo the shortcut. You can run the tour again later from Settings.

The shortcut block

This is what Spotlight adds to the end of ~/.config/hypr/bindings.lua:

-- >>> spotlight setup tour (managed; rerun via "Run Setup Tour") >>>
o.bind("ALT + SPACE", "Spotlight", "omarchy-shell shell toggle io.github.maajix.spotlight '{}'")
-- <<< spotlight setup tour <<<

• When you give Spotlight a combination another bind already uses, the block also contains an hl.unbind("...") line for it.
• If you wrote your own binding for the same toggle command, Spotlight comments it out with the prefix -- spotlight-tour:disabled , so only one binding opens it. Bindings that pass a query are left alone.
• Every shortcut change replaces the whole block, so do not edit between the markers. Change the shortcut from Spotlight Settings instead.

If the shortcut does not respond

Spotlight claims nothing when AltSpace is taken or when Hyprland could not report its bindings as the plugin loaded. Open Spotlight from a terminal:

omarchy-shell shell toggle io.github.maajix.spotlight '{}'

Then pick a combination in the setup tour, or later under Settings, Shortcut, Change. More causes are on Troubleshooting.

Bind it by hand

To manage the binding yourself, add a line outside the marked block and reload Hyprland:

o.bind("ALT + SPACE", "Spotlight", "omarchy-shell shell toggle io.github.maajix.spotlight '{}'")

hyprctl reload

Older versions recommended CtrlSpace, which conflicts with fcitx5 on fresh Omarchy installs.

Open with a query filled in

The toggle command accepts a query, so a second binding can start a workflow:

o.bind("ALT + SHIFT + SPACE", "Spotlight reminder",
  "omarchy-shell shell toggle io.github.maajix.spotlight '{\"query\":\"remind me \"}'")

toggle closes Spotlight when it is already open. Use omarchy-shell shell summon with the same arguments to always open it with the query.

Update

omarchy plugin update io.github.maajix.spotlight

Omarchy fetches the latest version, shows the diff and asks before applying it. The update only fast-forwards, so local changes in the plugin folder block it, and a version that fails validation is rolled back. Omarchy then reloads its plugins, so Spotlight picks up the new code without a restart. Your settings, learning data and shortcut stay as they are. If Spotlight still looks stale, run omarchy restart shell.

Remove

1. Remove the shortcut

   Open Spotlight Settings, go to Shortcut and press Change. Press Undo, or Restore followed by a combination if Spotlight replaced a Spotlight bind you had before. Spotlight deletes its block, uncomments any lines it disabled and reloads Hyprland.

2. Remove the plugin

   omarchy plugin remove io.github.maajix.spotlight

   Omarchy asks for confirmation, disables the plugin and deletes its folder.

3. Delete leftover data (optional)

   Your settings, learning data and currency cache stay in place, so a reinstall picks up where you left off. For a clean removal, delete them:

   rm -f ~/.config/omarchy/spotlight.json
   rm -f ~/.local/state/omarchy/spotlight-usage.json ~/.local/state/omarchy/.spotlight-usage.lock
   rm -f ~/.cache/omarchy/spotlight-currency.json ~/.cache/omarchy/spotlight-currency.lock

If you already removed the plugin, clean up ~/.config/hypr/bindings.lua by hand: delete everything from the -- >>> spotlight setup tour line to the -- <<< spotlight setup tour <<< line, remove the -- spotlight-tour:disabled prefix from any lines that carry it, then run hyprctl reload. If you set Spotlight up by hand, also remove your own o.bind(...) line and the blur layer rule in ~/.config/hypr/looknfeel.lua (see frosted glass).

Once you have finished or skipped the tour, spotlight.json records that setup is complete. A reinstall that finds that file neither shows the tour nor claims a shortcut. Pick a shortcut with Run Setup Tour, or delete the file before reinstalling.

This walk-through assumes Spotlight is installed (see Installation). Each step takes under a minute. The footer at the bottom of the card names what Enter does for the selected row, and what ShiftEnter does when the row has a second action.

1. Open Spotlight

   Press AltSpace. With the field empty, you see a short list of apps, and later the apps, commands, files and windows you use most. If this is your first open, the setup tour appears. Press Esc to skip it for now: step 7 brings it back. Press Esc again on an empty field to close Spotlight. See The empty field.

2. Launch an app

   Type firefox (or any app you have). The app is at the top under Applications and the footer reads Open. Press Enter to launch it. Tab completes the app's name in the field instead. See Apps, windows and files.

3. Calculate something

   Type 20% of 250. The answer, 50, appears at the top under Calculator, before you press anything. Press Enter (Copy result) to copy it. Conversions work the same way: try 5 km in mi. See Calculator and conversions.

4. Find a file with f

   Type f invoice, with any word from a file name in your home folder. Only files and folders are listed now. Enter (Open) opens the file, ShiftEnter (Open folder) opens the folder it is in, and CtrlC copies its path. See Apps, windows and files.

5. List open ports

   Type ports:. Spotlight lists the TCP and UDP ports listening on your machine, with the process name where it can see it. Add a number to filter, as in ports:3000. On a TCP port, Enter (Open URL) opens it in the browser and ShiftEnter (Copy endpoint) copies the address. The other views work the same way: ssh:, docker:, wifi: and more. See System views.

6. Flip a toggle

   Type night light. The Toggle Night Light row shows a switch with the current state, and the footer reads Turn on or Turn off. Press Enter: the switch flips and Spotlight stays open, so you can flip it back. See Live toggles.

7. Open Spotlight Settings

   Type spotlight settings and press Enter. The settings panel opens: switch search sources on or off, pick a web search engine, set limits, change the shortcut, or press Run setup tour to see the tour you skipped. Changes save as you make them. Press Esc to go back to the search field. See Settings.

Next steps

Every source, one list

You do not choose what to search. As you type, Spotlight asks every source at once and merges the answers into one list:

• From the first character: apps, direct answers (calculations, unit and currency conversions, reminders, calendar events, URLs), view names such as ports:, bangs, and a row that searches the web.
• From the second character: open windows, commands and toggles, files and clipboard history.

Files and clipboard history join plain searches only while Include files in every search and Include clipboard in every search are on (see Settings). To search one source only, start with a filter such as f:, cb: or w:. Search syntax lists them all.

Sections and their order

Results are grouped into sections, always in this order:

Ranking happens inside each section. A row never moves to another section, however often you pick it, so web rows always come last and a local match always gets Enter first. Inside a system view such as docker:, entries keep the view's own order.

How text matches

Every word you type must appear somewhere in a row: its title, its subtitle, its keywords, or the initials of its title. Matching is not typo-tolerant: frfx does not find Firefox. Case never matters. Rows that pass are ranked by how well the whole query fits the title:

Direct answers such as a calculation always count as the best match. Rows with the same score fall back to the better text match, then alphabetical order.

Learning from what you pick

When you press Enter on, or click, an app, a window, a file or a command, Spotlight records it. Three things then lift that row: how recently you picked it, how often, and whether you picked it after typing the same text. The last one is why typing fi can put Firefox above Figma once you have opened Firefox that way a few times.

• Learning can lift a row past one match level, never two. A much-used app whose name starts with your text can pass an unused exact match. A row that only contains your text never beats an exact one.
• ShiftEnter, CtrlEnter and Shift-click never teach it. Clipboard entries, web rows, direct answers and command help are not learned.
• Windows are learned per app, not per window. A learned file that no longer exists drops out.

The data stays on your machine in ~/.local/state/omarchy/spotlight-usage.json. Turn off Learn from your choices in Spotlight Settings to rank without it; the data is kept for when you turn it back on.

Reset learning Changed in 1.6.1

Open Spotlight Settings and press Reset learning data under Maintenance. The button changes to Press again to reset. Press it again to delete the file; the button then reads Learning data cleared. The old Reset Spotlight Learning result no longer exists.

The empty field

With nothing typed, Spotlight shows up to five apps. Once it has learned something, the apps you use most come first and the list adds up to one command, two files and two open windows you picked before. With learning off or nothing learned yet, you see five apps only.

Late results and the selection

Files, clipboard history, web suggestions, currency rates and command help come from background lookups and can arrive a moment after you type. An answer for text you have since changed is dropped.

• Until you move the cursor, the selection is whatever row is on top. Web rows always sort last, so a late suggestion never takes Enter away from a local result. A late file result can still land above a window match and become the top row.
• Once you move with the arrow keys, PageUp, PageDown or the mouse, the selection stays on that row while others arrive. If the row disappears, the selection returns to the top.
• Editing the query releases the selection again. The mouse is ignored for a moment after each key press, so a pointer resting over the list does not grab the selection while you type.

Confirmations

Log Out, Restart, Shut Down and disconnecting a connected device in bluetooth: need two presses. The first Enter arms the row, which then reads Press ↵ again to confirm. The second runs it. Moving the cursor, editing the query or closing Spotlight disarms it. Everything else runs on the first press.

The result limit

The whole list stops at Results shown (20 by default, 8 to 50), and so do filtered lists such as f: and cb:. System views are the exception. Because the lower sections come last, a short, broad query that matches many apps and commands can push windows, clipboard entries and the web search row off the end. Type a little more, use a filter, or raise the limit in Settings (maxResults).

Every setting has a control in the settings panel, and every control writes to ~/.config/omarchy/spotlight.json for you. Settings reference describes each key in detail.

Open the panel

Open Spotlight, type spotlight settings and press Enter on Spotlight Settings. Changes save as you make them, and anything still pending is saved when you leave. Press Esc or Done to go back to an empty search field.

• Tab moves between controls. A click or Space flips a switch; Enter does not.
• Number controls change with their - and + buttons or with Left and Right.
• The engine list opens with Enter, Space or Down. Move with Up and Down (or j and k), pick with Enter, close with Esc.

Controls

The panel groups its controls into six sections.

Search

Each Include option is greyed out while the source above it is off.

Web

Currency

Results

Shortcut

Open Spotlight shows the combination that opens Spotlight, or None. Press Change to pick another, as described in Change the shortcut.

Maintenance

The Setup and data row has three buttons. Run setup tour starts the tour. Data folder closes Spotlight and opens ~/.local/state/omarchy, where the learning data lives. Reset learning data deletes that data, as described in Reset learning.

Change the shortcut

1. Open the shortcut step

   In Spotlight Settings, press Change next to Open Spotlight. The shortcut step of the setup tour opens on its own.

2. Pick a combination

   Choose ALT + SPACE, SUPER + SPACE or CTRL + ALT + SPACE. Each is labelled current, recommended or with the name of whatever uses it now. For another combination, click Click here to record a shortcut and press it; it needs at least one modifier. If nothing happens, Hyprland already uses that combination and keeps the keys to itself. Spotlight tells you whether your choice is free or which bind it takes over.

3. Set it

   Press Set shortcut, or Replace and set when the combination is taken. Spotlight rewrites its block in ~/.config/hypr/bindings.lua, reloads Hyprland and confirms with Shortcut set to and the combination. Press Esc to return to the panel.

To take a change back, press Undo in the same step. If Spotlight replaced a Spotlight shortcut you had before, the button reads Restore and that combination. Both remove Spotlight's block, turn back on any lines it commented out and reload Hyprland.

If the step reports Shortcut saved, but Hyprland could not reload it., run hyprctl reload. If it reports Could not write the shortcut., add the binding yourself as shown in Bind it by hand.

Run the setup tour again

Press Run setup tour in the panel, or search setup tour and press Enter on Run Setup Tour. Finish saves your choices from the search step. Esc or Skip tour discards them, though a shortcut you already set stays. Started from the panel, the tour returns you to it.

The tour's search step leaves out Include clipboard in every search and the three limits. Set those in the panel.

Reset learning Changed in 1.6.1

Press Reset learning data under Maintenance. The button changes to Press again to reset; press it again to delete ~/.local/state/omarchy/spotlight-usage.json. It then reads Learning data cleared, and ranking starts from scratch. To pause learning without losing what it knows, turn off Learn from your choices instead. The Reset Spotlight Learning result from earlier versions is gone.

Edit spotlight.json

Press Edit file in the panel header, or press ShiftEnter on the Spotlight Settings result (Edit spotlight.json). If the file does not exist yet, Spotlight first creates it with every default. It never overwrites a file that exists.

{
  "webSuggestions": false,
  "currencyRates": true,
  "searchEngine": "g",
  "defaultCurrency": "",
  "fileSearch": true,
  "fileSearchAlways": true,
  "clipboardSearch": true,
  "clipboardSearchAlways": true,
  "learningEnabled": true,
  "maxResults": 20,
  "maxApps": 8,
  "maxSuggestions": 4,
  "setupCompleted": false
}

Edit it by hand to copy your settings to another machine, or to set setupCompleted back to false: on the next open the tour appears again, and Spotlight claims AltSpace if you have no shortcut and it is free. Spotlight reads the file each time it opens and does not watch it, so close and reopen Spotlight to apply an edit. Keys Spotlight does not know are kept when the panel saves.

When a save fails

If Spotlight cannot write the file, the panel subtitle changes to Settings not saved: followed by the reason, and the search footer shows Settings not saved. If the panel was already closed, a desktop notification appears instead. Your change stays queued. Fix the cause, which is usually one of the file rules above, then open Spotlight Settings and press Retry save. Edit file still opens the file while saves are failing.

Frosted glass

Spotlight takes its colors from your Omarchy theme and is translucent by default. To blur what is behind it, turn on Hyprland blur and add a layer rule in ~/.config/hypr/looknfeel.lua:

hl.config({
  decoration = {
    blur = {
      enabled = true,
      size = 8,
      passes = 3,
      brightness = 0.8,
      contrast = 0.9,
      new_optimizations = true
    },
  },
})

hl.layer_rule({
  match = { namespace = "omarchy-spotlight" },
  blur = true,
  ignore_alpha = 0.4,
})

Keep ignore_alpha: Spotlight draws on a fullscreen surface, and the threshold limits the blur to the card. Run hyprctl reload to apply it.

You don't need a prefix to find apps, open windows or files. Type a name and matches show up in their own sections: Applications, Windows and Files. The prefixes below narrow the list to one kind.

a: app: w: window: f: file: f <text> file <text> files <text> ~/ /

Try it

Launch an app

Type part of the app's name. Apps match from the first character. Each word you type has to appear in the app's name, desktop id, generic name, description or keywords. A word of five letters or fewer also matches the initials, so vsc finds Visual Studio Code. Matching is by substring and forgives no typos: frfx does not find Firefox.

The row shows the app name, its generic name underneath (for example "Web Browser") and App on the right. Press Enter (Open) to launch it and close Spotlight. ShiftEnter launches it too, without counting the launch toward learned ranking. Tab writes the app's name into the field.

• Spotlight lists the apps that Omarchy's own launcher shows. An entry that is hidden there is hidden here too.
• A query shows up to 8 apps. Change this with Applications shown (3 to 24).
• Apps are ordered by how well the name matches, then by how often you pick them, then alphabetically.
• To list only apps, type a: or app: followed by at least two characters, such as a:fi. With one character the list stays empty. a firefox (with a space) is a normal search, not a filter.

Switch to a window

Type two or more characters of a window's title or app id. Each row shows the window title (or the app id when the window has no title), the app id underneath and Window on the right. The row does not show the workspace.

• Enter (Focus window) focuses the window and closes Spotlight.
• ShiftEnter (Close window) closes that window and Spotlight.
• Type window, switch or focus to list every open window.
• w: and window: show only windows. w firefox (with a space) is the Wikipedia shortcut instead: see Web search.
• Learning counts the app, not the single window, so focusing one terminal often lifts every terminal window.

Find files and folders

File search needs Files and folders turned on. With Include files in every search also on (the default), any query of two or more characters searches your home folder and adds up to 4 file rows to the mixed results.

For a full file list, start the query with f, file or files and a space, or with f: or file:: for example f invoice or file:invoice. These forms show only files and folders in your home, start at one character and show up to 50 rows, within the Results shown limit (20 by default). files: and a bare f are not filters. f: with nothing after it shows the hint "Type a search after “f:”".

Each row shows the name, the full path of its parent folder underneath, and File or Folder on the right.

• Enter (Open) opens it in its default app.
• ShiftEnter (Open folder) opens the folder that contains it.
• CtrlC (Copy path) copies the full path and closes Spotlight. It works while no text is selected in the field.

How files are matched and ranked

• Words match the file or folder name only, not the path. You can use up to 8 words, every word must match, and case is ignored.
• Each word is read as a regular expression, so . matches any character and an invalid pattern finds nothing.
• Hidden files are searched, but anything hidden, or inside a hidden folder, ranks lower. .git, node_modules and .cache are skipped, and ignore files such as .gitignore are respected.
• An exact name ranks first, then a name that starts with your text, then a match at a word start, then anywhere in the name, then initials. Each folder level deeper costs a little, and files you open often rank higher.
• The search stops after 400 hits and after 3 seconds, and it does not cross into other mounted filesystems. With a broad word on a big home folder, the file you want can be cut off: add a word or search a folder.
• File rows arrive a moment after you stop typing. If you have not moved the selection, a late file can become the top row.

Search inside a folder

Start the query with ~/ or /. Everything up to the last / is the folder and the rest is the name to match. ~/Downloads/ lists everything in Downloads and its subfolders, and ~/Downloads/inv matches names containing "inv" there. The same works outside your home, as in /etc/host.

• Folder queries work even with Include files in every search off. Files and folders must be on.
• ~ alone, ./ and relative paths are not folder queries. / alone shows no files.
• A folder that does not exist gives no file rows.
• Folder queries never show web suggestions.

Settings

• fileSearch: turns file search on or off everywhere, prefixes included.
• fileSearchAlways: adds files to every search. When off, files appear only after f, f: or a path.
• maxApps: how many apps a query can show.
• maxResults: how many rows the list holds in total.
• learningEnabled: whether the apps, windows and files you pick rank higher over time.

Troubleshooting

Spotlight searches the text entries in Omarchy's clipboard history, so a link, command or address you copied an hour ago is a few keystrokes away. Type one of these prefixes to search the clipboard alone. Case does not matter.

cb: clipboard: cb <text> clip <text> clipboard <text>

Try it

Find an earlier copy

Type a prefix and a word from the text you copied. The prefix forms start matching at the first character. Without a prefix, Spotlight adds clipboard matches to every query of two or more characters while Include clipboard in every search is on. Any other prefix, such as f:, leaves the clipboard out.

Each row shows the copied text on a single line in a monospace font, with line breaks and runs of spaces joined into one space. Text longer than 120 characters is cut with "…". The right side reads Clipboard.

• Only those first 120 characters are searched. Every word you type has to appear in them.
• Rows are sorted by how well they match, then alphabetically, not by when you copied them.
• Up to 50 entries can match, newer ones first, and the Results shown limit still applies.
• Clipboard rows don't learn from your picks.
• c, c: and clip: are not clipboard prefixes. Use cb: or clip followed by a space.

Copy an entry back

Select the row and press Enter (Copy to clipboard). Spotlight puts the entry's full text (up to 1 MB) back on the clipboard, not only the one-line preview, and closes. It does not paste for you: switch to your app and paste as usual. ShiftEnter does the same.

Before copying, Spotlight reads the history again and checks that the entry still matches the row you selected. If it has changed or is gone, nothing is copied and no message appears.

Where the history comes from

Spotlight reads ~/.local/state/omarchy/clipboard-history.json, the history that Omarchy's clipboard panel keeps. It only reads this file and never changes it. What it reads:

• Text entries only. Images and other entries are skipped.
• The 200 most recent text entries. Older ones stay in Omarchy's history but are not searched.
• A history file of at most 8 MB. If the file is bigger, no clipboard rows appear.

To see or paste images, open Omarchy's own panel with the Clipboard History command: type history or cmd:clipboard.

Settings

• clipboardSearch: turns clipboard search on or off, prefixes included. Shown in the panel as Clipboard history.
• clipboardSearchAlways: adds clipboard matches to every search. Shown as Include clipboard in every search.
• maxResults: how many rows the list holds in total.

Troubleshooting

You don't need a prefix. When the query looks like math or a conversion, the answer shows up at the top under Calculator or Conversions while you type. Use a prefix to hide everything else, or = to make Spotlight treat the query as math.

calc: = unit: convert:

Try it

Calculate an expression

Type the expression. A Calculator row appears when the query has a number (or pi, tau, e) and an operator, a function or one of the words mod, x, pi or tau. The row shows the result, with the expression underneath. A query that fails to evaluate (a syntax error, division by zero, sqrt(-1)) shows no row.

Spotlight does not treat a query as math when it starts like a clock time (12:30), a version number (1.2.3) or a path, or when it contains other words. A leading = overrides this check: =e gives 2.7182818285, and =1e6/3 gives 333 333.3333333333. You also need = for ×, ÷ and −, and for scientific notation.

Operators

A leading minus binds tighter than a power, so -2^2 gives 4. Commas group thousands: 1,234.5 * 2 gives 2 469. Implicit multiplication (2pi), factorials and // are not supported.

Percentages

% always means percent, never remainder. 10 % 3 shows no row: use 10 mod 3.

• 20% of 250 gives 50.
• 250 + 10% gives 275, and 100 - 15% gives 85: adding or subtracting a percentage works on the number before it.
• 15% of 80 + 2 gives 14.
• Anywhere else, N% means N divided by 100.

Functions and constants

• Constants: pi, tau, e.
• One argument: sqrt, cbrt, abs, round, floor, ceil, sign, ln, log (base 10), log2, exp, and sin, cos, tan, asin, acos, atan in radians.
• Several arguments: min, max, hypot, and pow with two. max(3, 7, 5) gives 7 and hypot(3,4) gives 5.
• Parentheses are required: sqrt(4) works, sqrt 4 shows no row.

Copy the result

Results are rounded to 10 decimal places, so 0.1+0.2 gives 0.3 and 1/3 gives 0.3333333333. Digits are grouped with spaces. From 1e15 up, results keep 10 significant digits without grouping: 2^64 gives 18446744070000000000. Press Enter (Copy result) to copy the number without the spaces and close Spotlight. ShiftEnter does the same.

Convert units

Write an amount, a unit, a target word and a target unit: 10 km to mi. The space before the unit is optional (72f in c), and the target word can be to, in, as, ->, → or =. You always need a target unit, and both units must be from the same family. The row shows the result, with the full conversion underneath (for example "10 km = 6.2137 mi"), and Conversion on the right. Enter (Copy result) copies the result with its unit and without spaces, such as 6.2137mi.

• Unit names ignore case, so mb and MB both mean megabyte. kb, mb, gb are decimal, kib, mib, gib are binary, and bits are kbit, mbit, gbit.
• m is metre. For minutes write min. A month counts as 30.4375 days and a year as 365.25 days.
• ton is the metric tonne. Volumes are US customary. Write floz, sqft or ft2: fl oz and sq ft with a space don't work.
• in is also inches: 1 in in cm gives 2.54 cm.
• A comma is a decimal point here: 1,5 km to m gives 1 500 m, and 1,000 m means 1 m. Thousands separators, exponents and expressions are not accepted.
• Results keep 2 decimals from 100 up, 4 from 1 up, and 6 below 1.
• Spotlight converts durations but does not do clock arithmetic. For times and dates, see Calendar and reminders.

Convert currency

Write an amount with a currency code, name or symbol, then a target: 100 USD to EUR, 100usd in eur, $100 to euros, 100 dollars -> euro, £100 to yen. The same target words as for units apply.

• Codes: about 160 ISO codes, including gold (XAU) and silver (XAG). No cryptocurrencies.
• Names and symbols: $, US$, dollar for USD; €, euro for EUR; £, pound, sterling for GBP; yen for JPY; yuan for CNY. Plurals such as dollars work. ¥ is not accepted because it could mean either yen or yuan.
• A comma is a decimal point: 1,000 USD to EUR converts 1 dollar. 1,000.50 and 1 000 show no row, so write 1000.
• The whole query must be the conversion: extra words after the target show no row.
• A unit wins over a currency: 10 pounds to kg converts weight.

Convert to your default currency

Set Default currency in Spotlight Settings and a query without a target converts to it: 23 USD, $23 or 23 dollars. An explicit target still wins. Without a default, these queries show no row. Lowercase codes and pound don't count without a target (23 usd, 10 pounds), so a unit you are still typing is not taken for a currency.

How exchange rates are fetched

Rates come from Frankfurter, a free service that needs no account or API key. Spotlight asks for a rate only after you pause for 250 ms on a complete query. It sends the two currency codes, never the amount.

• While the rate loads, the row reads "Loading exchange rate…" and the footer shows Copy when ready. Press Enter and the result is copied as soon as it arrives, as long as you haven't changed the query.
• Once converted, the row shows the amount in the target currency. Underneath is the calculation, "Frankfurter" and the date of the rate. Enter (Copy result) copies the number only, with no spaces or code.
• Rates are cached for 24 hours in ~/.cache/omarchy/spotlight-currency.json, for up to 128 pairs. If a refresh fails, Spotlight shows the older rate and adds "Cached · refresh unavailable", then tries again after a minute.
• With no rate at all, the row reads "Exchange rate unavailable" and can't be selected.
• Converting a currency to itself needs no network. Historical rates are not available.

Settings

• currencyRates: whether Spotlight fetches rates from Frankfurter. On by default. Shown as Currency rates.
• defaultCurrency: the three-letter code used when a query has no target. Empty by default. The panel field accepts a valid code or nothing and turns red for an unknown code.

{ "currencyRates": true, "defaultCurrency": "EUR" }

Troubleshooting

Start a query with a reminder phrase or an event word, add a time in plain English (a few German words work too), and a row under Reminders or Calendar shows what Spotlight understood before you press anything. The reminder: prefix adds "reminder" to your text, and calendar: and event: add "event".

remind me reminder: reminders event meeting calendar: event:

Try it

Set a reminder

Start with remind me, remind, reminder, remember or the German erinner mich / erinnere mich. Add a time from the table below and a message, in either order. Spotlight drops a leading "to", "that", "about" or "for" from the message and capitalizes its first letter, so remind me to call bob in 20m gives "Call bob".

The row shows the message, with "Notify" plus the time and how far away it is underneath, for example "Notify today at 10:20 · in 20 min". Press Enter (Set reminder) to schedule it and close Spotlight. ShiftEnter does the same.

• Without a time, the row reads Needs a time and suggests adding one, such as “in 20m”, “at 15:30” or “tomorrow at 9”. It can't be selected.
• A time without a message (remind me in 20m) shows no row.
• Reminders count whole minutes, rounded up, with a minimum of one: in 30s becomes 1 minute.

Spotlight hands the reminder to Omarchy's reminder tool, which schedules a systemd user timer. Omarchy confirms with a notification such as "Call bob in 20 minutes" / "You'll be reminded at 10:20". When the time comes, you get a notification titled "Reminder" with your message.

See and clear reminders

Type exactly reminder or reminders. Each active reminder is listed with its message and "in … · at …" underneath. These rows are for reading only. The last row, Clear all reminders, shows how many are active; Enter (Clear) cancels all of them. You can't cancel a single reminder. With none set, you see "No active reminders".

Add a calendar event

Start with cal, calendar, event, meeting, appointment, appt, schedule or termin. Without one of these words, Spotlight still offers an event when the query has a clear time phrase, such as a clock time, a date or "in 3 days", and some text for the title: call with ops at 3pm. A weekday alone is not enough, so note friday ideas stays a normal search.

The row shows the title, with the time and length underneath ("tomorrow at 14:00 · 1h 30m" or "15 Jan 2027 · All day"), and Calendar on the right.

• Enter (Add to Google Calendar) opens Google Calendar's new-event page in your browser, with the title and time filled in. Nothing is saved until you save it there.
• ShiftEnter (Save .ics file) writes a calendar file named like omarchy-event-….ics to ~/Downloads and opens it with the default app for .ics files. Existing files are never overwritten.

Title, length and all-day events

• The title is what's left after the time phrase, capitalized. The trigger word is dropped (schedule review gives "Review"), unless "with" follows it (meeting with sarah keeps "Meeting with sarah"). With no other text the title is the trigger noun or "Event": cal 25 sep gives "Event".
• Set the length with for and minutes or hours: for 90min, for 1.5 hours, for 45 min, for 30m. The shortest event is 5 minutes. Without for, events last one hour.
• With no time at all, the event starts at the next full hour.
• A date without a clock time, or in 3 days, makes an all-day event. Adding for makes it a timed event again. Days are not a length: event tomorrow for 2 days gives an all-day event titled "2 days".

Time phrases

The same phrases work for reminders and events. The results below assume it is Wednesday 23 September 2026, 10:00.

• A weekday is always the next one after today. next friday on a Wednesday is two days away; said on a Friday, it is a week away.
• An hour below 12 without am or pm that has already passed today means the evening: at 10:00, at 9 and at 9:00 are 21:00. A time with am that has passed moves to tomorrow: at 9am is tomorrow 09:00.
• A date without a year means its next occurrence. A date without a clock time means 09:00 for a reminder and all day for an event.
• in with a bare number counts minutes: meeting in 2020 is 2020 minutes from now, not the year 2020.

Settings

Reminders and events have no settings of their own. See the settings reference for everything else.

Troubleshooting

Anything Spotlight cannot answer on your machine can go to the web in one keystroke. Every web result opens in your browser through Omarchy's browser launcher, and nothing is sent anywhere until you press Enter on it, unless you turn on search suggestions.

web: search: url: g … yt … aw … tr …

Try it

Search the web

Every query that is not empty and not a URL gets a web search row, for example Search Google for “pipewire latency”. Its footer label is Search Google (or the name of your engine) and it sits in the Web section. Press Enter on it to open the results page in your browser.

The web search row always ranks last, below every local result. When local results already fill the result limit (20 rows by default), it is dropped; put web: in front of the query to bring it back.

To change where it goes, open Spotlight Settings and pick an engine under Web, Web search engine. The list holds every site from the bang table. The same engine answers search suggestions.

Search only the web

Start the query with web:, search: or url: (all three do the same). Spotlight then hides apps, files, commands, calculations and everything else, and shows only web rows: an opened URL, a bang, suggestions and the web search row. With nothing after the colon you see the hint Type a search after “web:”.

Open a URL

Type or paste an address without spaces and Spotlight offers it as a row in the Direct links section, ranked above apps. The title shows the address without https://, the subtitle shows the full URL, and the footer label is Open in browser. A URL query gets no web search row.

A bare host name counts as a URL only when it ends in a known top-level domain: com, org, net, io, dev, de, co, uk, eu, app, sh, gg, ai, me, info, xyz, to, tv, so, rs, it, fr, es, nl, ch, at, se, no, pl, cz, jp, cn, us, ca, au, in, br, edu, gov, mil, int, local or test. A port and a path are allowed after it. That is why node.js stays a normal search. Addresses are recognized in the normal search and after web:, not inside other filters.

Jump to a site with a bang

Type a bang, a space and your search, for example gh omarchy. Spotlight adds a row whose title is your search text and whose subtitle and footer label name the site, here Search GitHub. Press Enter to open that site's search results. Bangs are not case-sensitive, and they need text after the space: gh on its own is a normal search.

The bang row sits in the Web section, below local results. If something on your machine also matches (an app, a command, a system view), it comes first: press Down to reach the bang row, or type web: in front so only web rows are left. For example docker nginx is a Docker Hub search, while docker: with a colon opens the Docker containers view.

The bang list is built in. You cannot add your own bangs.

Translate text

Use the tr bang and end with to, in or into and a language: tr wo ist der bahnhof to english. The row title shows only the text that will be translated, and the subtitle and footer label read Translate to English. Enter opens DeepL with that text and target. DeepL detects the source language itself.

• Without a target language the row reads Search DeepL and DeepL opens set to English to German.
• Only the last to, in or into counts. If the word after it is not a language, the whole text is translated: tr I want to go translates "I want to go".
• You can name the language in English or by its code: french or fr, german, deutsch or de.

Supported targets: Arabic, Bulgarian, Chinese (mandarin, zh), Chinese traditional (zh-hant), Czech, Danish, Dutch, English, Estonian, Finnish, French, Georgian, German, Greek, Hebrew, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian (no, nb), Polish, Portuguese, Brazilian Portuguese (brazilian, pt-br), Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Turkish, Ukrainian and Vietnamese.

Get search suggestions while you type

Search suggestions are off by default. Turn them on in Spotlight Settings under Web, Search suggestions. Spotlight then shows up to 4 completions for your query (change the number under Results, Search suggestions shown, from 0 to 8). Each suggestion's footer label is Search Google or your engine's name, and Enter searches for it with your engine.

Spotlight asks for suggestions only in the normal search or after web:, and only for queries of two or more characters. It never sends:

• URLs, bangs, calculations or currency conversions
• reminders or calendar events
• file searches (f:, f …, or a path starting with ~/ or /)
• any other filter, such as cb: or man:, and any system view

A request that takes longer than 3 seconds is dropped. More on this in Privacy and security.

Settings

• searchEngine: where the web search row and suggestions go. Default "g" (Google). Any bang key works; an unknown key falls back to Google.
• webSuggestions: turn search suggestions on. Default false.
• maxSuggestions: how many suggestions to show. Default 4, 0 to 8.
• maxResults: the result limit that decides when the web search row is dropped. Default 20.

Troubleshooting

Command help shows the tldr page for a command: a short description and a handful of practical examples. It is meant for the moment you remember the tool but not the flags. Despite the name, man does not open the full manual page; both prefixes show the same tldr examples.

man: tldr: man … tldr …

Try it

Look up a command

Type man or tldr, a space or a colon, and the command name. Upper and lower case do not matter. For a subcommand, keep typing words: tldr docker compose looks up the docker-compose page. While you use one of these prefixes, Spotlight shows only command help, no apps, files or web rows. With nothing after man: you see the hint Type a search after “man:”.

The page appears a moment after you stop typing. Page names can contain letters, digits, dots, underscores, plus signs and hyphens (up to 64 characters). A name with anything else, such as a slash, shows nothing.

Read the page

The results follow the order of the tldr page:

• Under Command help, a heading row with the page title and its one-line description. You cannot select it.
• One section per example. The section title is the example's description (for example "Create an archive and write it to a file"), and the row below it is the command in a monospace font. Up to 16 examples are shown.
• Under More information, the link the page points to, usually the project's own documentation. Enter opens it in your browser.

Spotlight tidies each example so it is ready to use: placeholder braces are removed ({{path/to/file}} becomes path/to/file), an option given in short and long form is shown in its long form ({{[-a|--all]}} becomes --all), and the description loses its bracket hints and trailing colon.

Copy an example

Select an example and press Enter (footer label Copy command). The command goes to the clipboard and Spotlight closes. Replace the placeholders, such as path/to/file, after you paste.

Open an example in a terminal

Press ShiftEnter (footer label Open in terminal; CtrlEnter and Shift-click do the same). Spotlight opens a new terminal with the command already typed at a bash prompt, not run. Edit the placeholders, then press Enter in the terminal to run it.

Where pages come from

Spotlight asks the tldr command-line client (included with stock Omarchy) for the page. The client downloads pages from the tldr-pages project on GitHub the first time you look one up and keeps them in ~/.cache/tldr. After that:

• A page you have looked up recently comes from the cache, with no network request. The client that ships with Omarchy refreshes a cached page after 7 days.
• Offline, a cached page still shows (the client falls back to its copy when the download fails). A page you have never looked up shows No tldr page for “…”.
• Spotlight waits at most 4 seconds for the client. A slower download also ends as No tldr page for “…”; try again once the network is back.

Spotlight itself sends nothing to the network for command help. The download is the tldr client's, and it only happens for pages that are not cached yet or are out of date. See Privacy and security.

Settings

Command help has no settings. Example rows are not learned, so copying one does not change how other results rank.

Troubleshooting

Omarchy's on/off commands, such as night light, Do Not Disturb or the Wi-Fi radio, show a switch in Spotlight that reflects the current state of your system. Flip one and the palette stays open, so you can see the change and flip another. Toggles are ordinary commands: search for them by name or keyword like any other result.

action: cmd:

Try it

Flip a toggle

Select a toggle and press Enter. The footer label says what will happen: Turn off while the switch is on, Turn on while it is off. ShiftEnter, CtrlEnter and a click do the same.

Spotlight runs the Omarchy command, moves the switch at once and keeps the palette open. About two and a half seconds later it reads every state again, so the switch corrects itself if the command did not take effect. Press Esc when you are done.

Commands start matching at two characters. To see only commands, start with action: or cmd: and type at least two characters after it.

How the state is read

Every time you open Spotlight, it checks the state of each toggle in the background. Most states come from Omarchy's own toggle files and are always known. The rest ask a tool (for example hyprctl, nmcli, rfkill or the audio server) and must answer within one second.

The switch shows what was true when the palette opened, plus your own flips. It does not follow changes made elsewhere while Spotlight is open; close and reopen it to read again.

If a state cannot be read (the tool is missing, slow or has nothing to report), the row has no switch. It then behaves like a normal command: the footer reads Run, and Enter runs the command and closes the palette.

All live toggles

"On" in the last column is the state in which the switch is shown on.

Other commands have no switch, even when they sound like one. Screensaver starts the screensaver now, and entries that come from the Omarchy menu run once and close the palette.

Reach the Bluetooth and Wi-Fi toggles Changed in 1.6

Since 1.6, bluetooth and wifi are also the names of system views. When you type a view's full name, Spotlight selects the view row (section Views, footer Open view), even if an app has the same name. Enter fills in bluetooth: or wifi: and lists your paired devices or nearby networks. The same happens for a start such as blue, unless an app name starts with those letters.

The toggle is still in the list, further down under Commands. To reach it:

• press Down until it is selected, or
• type toggle bluetooth or toggle wifi, or
• type radio, which finds both.

Learning

A toggle you flip with Enter is learned like any other command, so it moves up for the words you use to find it and can be the command Spotlight offers when you open it with an empty query. See How search works.

Settings

• learningEnabled: whether flipping a toggle counts towards ranking. Default true.

Toggles have no settings of their own.

Troubleshooting

A system view is a list of live things on your machine, such as open ports, containers or audio devices, fetched when you open it. Type the view's name and a colon, narrow the list with a few letters, then press Enter to act on a row: open a port in the browser, follow a container's logs, switch your speakers. There are eight views.

ports: ssh: docker: services: mounts: audio: wifi: bluetooth:

Try it

Open a view

Type the view name followed by a colon, for example docker:. Case does not matter and a space after the colon is fine. The list appears straight away, first as a loading row, then with the entries.

You do not have to type the colon. While you type a letter or more that starts a view name, the matching views appear at the top in a Views section (footer label Open view): s offers ssh: and services:. Press Enter or Tab on one to fill in the name and colon.

• A full view name such as ports always selects the view, even when an app has the same name. That is why bluetooth and wifi open their views rather than the toggles (see Live toggles).
• For a partial name, an app or other result that starts with the same letters can keep the selection; the view rows stay at the top, so press Up to reach them.
• With more words and no colon, the view is not involved: docker nginx is a Docker Hub search.

Filter a view

Text after the colon filters the list that was already fetched; it never runs the command again. Each word you type must appear somewhere in the row's searchable fields (listed for each view below). Exact matches rank first, then matches at the start of a field or word, then matches anywhere. In ports: an exact port number and in ssh: an exact host name always come first.

Views ignore the result limit (maxResults), are never sent as search suggestions and are not learned, so what you pick in a view does not change other rankings.

Keys in a view

An action closes Spotlight before it runs. Actions that need a terminal (SSH, logs, Wi-Fi connect) open a new one. When the logs or nmcli command ends, for example after you press CtrlC in it, the terminal stays open with Process exited (N). Press Enter to close.

Loading, empty and error states

A list is partial when there were more entries than the view shows (200 rows, or 100 for audio, Wi-Fi and Bluetooth), when the tool's output was too large or too slow to read in full, or for the reasons given under services and SSH. Status rows cannot be selected.

Refresh a view

Spotlight fetches a view once, when you open it, and does not refresh it while you look. To fetch again, delete the colon and type it again, switch to another view and back, or close and reopen Spotlight.

Open a listening port

ports: lists the TCP and UDP ports that something on your machine listens on, from ss. UDP includes every bound UDP socket, so browsers and mDNS (port 5353) show up too.

• Each row: the process name, the endpoint (such as *:8080, 127.0.0.1:5432 or [::1]:631) with its PID, and TCP or UDP. Sorted by port.
• Enter on a TCP port (Open URL) opens http:// with the address and port in your browser; a port open on all addresses opens as localhost. On a UDP port, Enter is Copy endpoint.
• ShiftEnter (Copy endpoint) copies the endpoint text.
• The filter matches the process name, endpoint, protocol and PID. It also accepts letters in order as a shorthand for a process name, so ports:psgr finds postgres, ranked below direct matches.

Linux shows the process name and PID only for your own sockets. Ports owned by root or other users, such as sshd, appear as Port 22 with no PID. The URL is always http://, so Open URL is not useful for SSH or HTTPS ports; copy the endpoint instead.

Connect to an SSH host

ssh: lists the Host aliases in ~/.ssh/config and the host names in ~/.ssh/known_hosts, saved hosts first. Spotlight reads these files itself; it does not run anything to build the list.

• Each row: the host name, Saved host · ssh name or Known host · ssh name, and SSH.
• Enter (Connect) opens a terminal running ssh name. When you log out the terminal closes; if ssh cannot connect, it stays open so you can read the error.
• ShiftEnter (Copy command) copies ssh name.
• The filter matches the host name only.

To reach a host you have not saved, type it: ssh:deploy@10.0.0.1 adds Connect to deploy@10.0.0.1. This row also appears when a longer saved name matches (typing 10.0.0.1 while 10.0.0.12 is saved). It accepts a host name or IPv4 address with an optional user@; a port (host:2222), an IPv6 address, spaces or a leading - get no connect row, and if no saved host matches either you see No matching SSH hosts. Put a port in ~/.ssh/config instead.

• Wildcard and negated patterns (Host *, Host !x), hashed known_hosts lines and [host]:port entries are not listed.
• Include is followed for files inside ~/.ssh, when it appears before the first Host block or under Host * (up to 32 files, 4 levels deep).
• Spotlight skips a file that is a symlink, is not owned by you, is writable by group or others, or is too large (64 KB for config files, 256 KB for known_hosts). Its hosts are missing and the list is marked partial.

Follow a container's logs

docker: lists your containers, running and stopped, from the docker command. Running containers come first, then by name. Only the newest 200 are shown.

• Each row: the container name, its image, status and published ports, and its state (running, exited, created, paused and so on).
• Enter (Follow logs) opens a terminal showing the last 100 log lines and following new ones.
• ShiftEnter (Copy ID) copies the full container ID.
• The filter matches name, image, status, ports and ID. docker:up finds running containers, because their status reads "Up 3 hours" and so on.

The view needs access to the Docker daemon without sudo. Stock Omarchy does not give you that, because membership in the docker group is equivalent to root. To opt in, open the Omarchy menu and choose Setup, Security, Sudoless Docker (undo it under Remove, Security, Sudoless Docker), or use rootless Docker. Without access, or when the daemon is stopped, you see Docker unavailable · check daemon access. The view uses your active Docker context, which can point at a remote machine.

Follow a service's logs

services: lists the loaded systemd services of your user session and of the system, including loaded ones that are inactive. Unit files that are not loaded do not appear. Failed services come first, then active ones, user before system.

• Each row: the unit name without .service, its state such as active / running with the description, and user or system.
• Enter (Follow logs) opens a terminal with the unit's last 100 journal lines, following new ones.
• ShiftEnter (Copy unit name) copies the full name, for example bluetooth.service.
• The filter matches the unit name, description, state and scope: services:failed, services:running, services:user. A word can also match a description.

If one of the two lists cannot be read, you get the other one marked as partial; if neither can, Services unavailable.

Open a mounted filesystem

mounts: lists mounted real filesystems from findmnt, leaving out pseudo filesystems such as proc and sysfs.

• Each row: the mount point, the source device (Btrfs subvolumes appear as /dev/mapper/root[/@home]) and the filesystem type.
• Enter (Open mount) opens the folder in your default file manager.
• ShiftEnter (Copy path) copies the mount point.
• The filter matches mount point, source and type: mounts:btrfs, mounts:boot.

When several filesystems are mounted on the same folder, the row shows the one on top. If findmnt output is too large or too slow, the view shows Mounts unavailable rather than a partial list.

Switch the audio device

audio: lists your audio outputs and inputs through PipeWire's PulseAudio layer (pactl), in two sections: Audio outputs, then Audio inputs, the default device first in each. Monitor inputs are left out.

• Each row: the device description, Default or Available with the volume and Muted if muted, and Output or Input.
• Enter (Set as default) makes the device the default and moves sound that is already playing to it, as Omarchy's audio panel does. On the current default the label reads Current default and Enter does nothing; Spotlight stays open.
• There is no second action.
• The filter matches the description and device name, plus the words output, speaker and headphones for outputs, and input, microphone and mic for inputs. So audio:mic lists every input and audio:headphones every output.

To mute rather than switch, use the Toggle Speaker and Toggle Microphone commands.

Join a Wi-Fi network

wifi: lists the networks NetworkManager found in its last scan. Opening the view does not start a new scan, so the list can be a little out of date. Networks you are connected to come first, then by signal strength.

• Each row: the network name, Connected or Available with the signal percentage and security type (such as WPA2), and Connected or Wi-Fi.
• Enter (Connect) opens a terminal running nmcli, which asks for the password when the network needs one. On the network you are connected to, the label is Manage network and Enter opens Omarchy's network panel.
• There is no second action.
• The filter matches the network name and security type only, not whether you are connected.
• With no filter, the last row is Manage Wi-Fi… (footer Open panel), which opens the network panel. With no networks at all it reads No Wi-Fi networks · open Network panel.

Hidden networks are not listed. A name that appears on several access points is shown once (the connected or strongest one), and names containing invisible or control characters are skipped. The view needs nmcli and a running NetworkManager.

Connect a Bluetooth device

bluetooth: lists the devices you have paired, read from the Bluetooth service over D-Bus with busctl. Connected devices come first, then by name. The Bluetooth service must be running.

• Each row: the device name, Connected or Paired, and Bluetooth.
• Enter (Connect) turns the adapter on if needed, marks the device as trusted and connects it.
• On a connected device the label is Disconnect, and it needs a second press: the first Enter shows Press ↵ again to confirm. Moving the selection or typing cancels it.
• There is no second action.
• The filter matches the device name and its address (bluetooth:AA:BB).
• With no filter, the last row is Pair another device… (footer Open panel), which opens Omarchy's Bluetooth panel for pairing. With no paired devices it reads No paired devices · open Bluetooth panel.

Settings

System views have no settings. They are not affected by maxResults, webSuggestions or learningEnabled.

Listing a view sends nothing over the network, except that the docker command talks to whichever daemon your Docker context names. Spotlight runs every tool directly, without a shell, and never passes a name from a list as a command-line option. See Privacy and security.

Troubleshooting

More fixes are in Troubleshooting.

All views at a glance

Without a prefix, Spotlight searches everything at once and ranks the results together. A prefix narrows the search to one provider. For how the mixed list is ranked, see How search works.

Filters at a glance

The last eight are system views. Added in 1.6

Colon filters

A filter is a known word followed by a colon, then your search. Only that provider runs, so nothing else appears in the list. Filters ignore case and the space after the colon is optional: F:invoice, f:invoice and f: invoice are the same query.

• Unknown words stay text. If the word before the colon is not in the table above, the whole query is an ordinary search. c:, clip:, port: and bt: are not filters.
• Nothing after the colon. A provider filter shows only a hint row, such as Type a search after “f:”. A view lists its entries right away.
• Minimum length. a:, w: and action: need 2 characters after the colon; with 1 the list is empty. f:, cb: and man: start at 1 character.
• Tool filters show one row. calc:, unit:, reminder: and calendar: show only that tool's row: no apps, files or web results.
• Reminder and event filters add the trigger word. reminder: call mom in 20m reads as reminder call mom in 20m, and event: dentist friday at 10 as event dentist friday at 10.
• Files always start at home. f: searches your whole home directory. To search inside one folder, use a path query.
• Views filter as you type. Text after a view name narrows its list, as in ports:22. Views have no aliases and no short forms. See System views.
• Row limit. Filtered lists are cut at maxResults (20 by default). Views are not.

Short forms without a colon

Three providers also accept a word, a space and your search. These are exclusive, like the colon forms.

• Text after the space is required. f or man alone is an ordinary search.
• No other filter has a short form. a firefox, calc 2+2, web foo and unit 5kg are ordinary searches.
• w firefox is the Wikipedia bang, not a window filter. Use w:firefox for windows.

Bare view names

When the whole query is letters, with or without a trailing colon, and starts a view name, Spotlight adds a completion row for each matching view at the top of the list. The row reads ports: with the view title below it, sits in the Views section, and shows Open view in the footer. Added in 1.6

Enter or Tab on a completion row writes name: into the field and opens the view. The rest of the mixed search still runs below the completion rows, so Enter does not always pick the view. See Which row Enter picks.

Path queries

A query that starts with ~/ or / searches files below that folder. Everything up to the last slash is the folder; the rest is the name pattern.

• ~/Downloads/ lists everything below ~/Downloads, including subfolders.
• ~/Downloads/inv searches for inv below ~/Downloads.
• ~ alone, ./ and relative paths are not path queries.
• A path query is not exclusive: apps, commands and other results can still appear. Files need at least 2 characters, so / alone shows no files.
• A path query shows up to 50 files, then the maxResults cap applies. A folder that does not exist gives no files.
• Path queries need fileSearch on and never send web suggestions.

File patterns match file and folder names, not full paths, and are read as regular expressions, so . matches any character. Spotlight skips .git, node_modules and .cache, respects ignore files, and stops after 400 matches. More in Apps, windows and files.

Bangs

A bang is an engine key, a space and your search: gh omarchy, yt lofi, aw hyprland. It adds a row that opens that site's search in your browser. The full list of keys and sites is in Web search and bangs.

• Keys: g, gg, google, ddg, kagi, yt, gh, w, wde, aw, aur, pkg, so, mdn, npm, crates, docker, maps, tr, img, hn, omarchy. They ignore case.
• The search text is required. gh alone is an ordinary search.
• Bang rows sort below every local result, so w firefox usually selects the Firefox app. Press Down to reach the bang.
• tr translates with DeepL. End the text with to, in or into and a language, as in tr guten morgen to english; the row then reads Translate to <Language>. The last match wins, and an unknown language stays part of the text.

URLs

A query without spaces that looks like an address shows Open in browser in the Direct links section. This works in a plain search and under web:.

A bare host name opens only with one of these endings: com org net io dev de co uk eu app sh gg ai me info xyz to tv so rs it fr es nl ch at se no pl cz jp cn us ca au in br edu gov mil int local test. So node.js and foo.local.lan stay searches, while foo.local opens.

Answers without a prefix

These appear in a plain search as soon as the text matches. The filter in brackets shows only that answer.

Precedence and ambiguity

Spotlight trims the query and then reads it in this order:

1. A colon filter or view name before a colon: only that provider or view runs.
2. A short form (f, file, files, cb, clip, clipboard, man, tldr) with text after it: only that provider runs.
3. Anything else is a mixed search. View completions, answers, apps, bangs and the web fallback start at 1 character; windows, commands, files and clipboard entries join at 2.

Which row Enter picks

Completion rows always sit at the top, but Enter picks the first match of these rules:

1. The text is a view's full name and no other view matches: the view. docker selects docker: even with an app called Docker installed.
2. An app whose name equals the text.
3. One view matches: the first app whose name starts with the text, otherwise the view. port selects an app called Portal; blue selects bluetooth:.
4. Several views match: the first answer, app or command. s selects Settings, not ssh:.

When no view completes, Enter picks the top row. Once you move the selection with the arrow keys or the pointer, Enter acts on the row you chose until you edit the query.

Same word, different meanings

Limits

• The query is cut at 512 characters.
• Every plain or web: query that is not a URL ends with Search <Engine> for “query”. It is always the last row, so it drops off when local results fill maxResults. The engine is searchEngine.

Quick reference

Open and close Spotlight

AltSpace opens Spotlight from anywhere, and pressing it again while Spotlight is open closes it. Spotlight binds it on first run if nothing else uses it. To pick another combination, open Spotlight Settings and press Change under Shortcut; see Settings.

Every open starts fresh, with an empty query unless the binding passes one. Spotlight closes when you:

• press Esc on an empty query,
• click outside the card,
• switch to another window or workspace,
• run most actions.

It stays open after you flip a toggle whose state it knows, fill in a view name, arm a confirmation, or open Spotlight Settings or Run Setup Tour.

Add a shortcut with a starting query

Your shortcut runs omarchy-shell shell toggle io.github.maajix.spotlight '{}'. Put a query in the braces to open Spotlight with text already typed. Add your own binds outside the block Spotlight manages:

o.bind("ALT + SHIFT + SPACE", "Spotlight reminder",
  "omarchy-shell shell toggle io.github.maajix.spotlight '{\"query\":\"remind me \"}'")

Like the main shortcut, toggle closes Spotlight when it is already open. To always open with the query, even over an open Spotlight, use summon in place of toggle. The query is cut at 512 characters.

In the search field

The field keeps focus the whole time, so these keys work while you type.

CtrlN and CtrlP work only with no other modifier held.

Selection

Until you move it, the selection follows the top row, and Enter goes to the best match as results arrive. Which row that is when a view name completes is explained in Search syntax.

Once you move the selection with the arrow keys, PageDown/PageUp or the pointer, it stays on that row while late results arrive. Editing the query releases it back to the top row.

Mouse

• Moving the pointer over a row selects it. Spotlight ignores the pointer for 400 ms after it opens and after each key press, so a resting pointer does not steal the selection while you type.
• Click runs the main action. Ctrl-click does the same.
• Shift-click runs the second action.
• Clicking outside the card closes Spotlight.

Footer hints

The footer names the actions of the selected row:

• ↵ <label> is what Enter does. Toggle rows read Turn on or Turn off. Hint rows show no Enter hint.
• ⇧↵ <label> appears only when the row has a second action.
• ⌃C Copy path appears on file and folder rows.

The left side reads Omarchy, or Settings not saved after a settings write failed.

Enter and Shift+Enter by row

Only a plain Enter or click on an app, window, file or command teaches Spotlight what you prefer; see learningEnabled. ShiftEnter, CtrlEnter and Shift-click are never learned.

System view rows

The manage row some views show on an empty filter reads Open panel. Tab does nothing on view rows, and CtrlC does not copy a path from them, not even on mounts:; use ShiftEnter there.

Confirmations

Log Out, Restart, Shut Down and disconnecting a connected Bluetooth device need two presses. The first Enter (or ShiftEnter) arms the row, and it reads Press ↵ again to confirm. The second press runs it. Moving the selection, editing the query or reopening Spotlight disarms the row.

Settings panel

The panel opens with nothing focused. Press Tab to walk through the controls.

Clicking outside closes Spotlight entirely; changes you made are still saved.

Setup tour

In the default currency field, Left only moves the cursor and Esc undoes the edit; neither leaves the step.

Record a shortcut

On the shortcut step, the recorder takes focus and reads Press your shortcut. Press a combination with at least one modifier and one of these keys: Space, Tab, Backspace, Return, Delete, Print, an arrow, A to Z, 0 to 9 or F1 to F12. Modifier-only presses are ignored. If the recorder is not focused, it reads Click here to record a shortcut.

• While the recorder has focus it takes every key except Esc, Enter and Tab, so Left does not go back. Press Tab first, or use Back.
• Hyprland keeps combinations it already binds, so nothing registers for them. The recorder says so: "Listening. If nothing happens, Hyprland already uses that combination."
• Pressing your current Spotlight shortcut on this step selects it instead of closing Spotlight.
• The presets ALT + SPACE, SUPER + SPACE and CTRL + ALT + SPACE are one click away.

When you open this step from the settings panel with Change, Left does nothing, and Esc returns you to the panel without changing any settings.

Spotlight keeps its settings in ~/.config/omarchy/spotlight.json. The file holds one flat JSON object with 13 keys. Most of them also have a control in the settings panel; see Settings for how to use it. The keyboard shortcut is not stored here: it lives in ~/.config/hypr/bindings.lua.

Full example

This is the file with every key at its default, exactly as Edit spotlight.json creates it. Leave out any key to use its default.

{
  "webSuggestions": false,
  "currencyRates": true,
  "searchEngine": "g",
  "defaultCurrency": "",
  "fileSearch": true,
  "fileSearchAlways": true,
  "clipboardSearch": true,
  "clipboardSearchAlways": true,
  "learningEnabled": true,
  "maxResults": 20,
  "maxApps": 8,
  "maxSuggestions": 4,
  "setupCompleted": false
}

A freshly created file says "setupCompleted": false. Spotlight only creates it when no file exists, and finishing or skipping the setup tour sets that key to true.

All keys

How Spotlight reads the file

• The file is optional. Without it, every key uses its default.
• Spotlight reads it each time it opens. It does not watch the file, so a hand edit applies the next time you open Spotlight.
• The file must be a regular file owned by you, at most 64 KiB, not a symlink, and not writable by group or others. Otherwise Spotlight ignores it, uses the defaults and does not start the tour.
• A value of the wrong type falls back to that key's default. Booleans must be JSON true or false, not "true" or 1. A number outside its range is moved to the nearest limit.
• If the file is not valid JSON, or is not an object, Spotlight uses the defaults, skips the tour and does not claim a shortcut. Every panel save fails with "spotlight.json is not a JSON object" until you fix it.
• The panel writes only the keys it knows. Keys you add yourself survive. Writes replace the file atomically with mode 0600, and the panel refuses a write that would make the file larger than 64 KiB.
• To create the file, run Spotlight Settings with ShiftEnter (Edit spotlight.json), or press Edit file in the panel. Both write the defaults above and never overwrite an existing file.

Search

fileSearch

Searches files and folders in your home directory by name. When false, nothing searches files: not f:, not the short forms such as f invoice, and not path queries.

Type

boolean

Default

true

Set in panel

Search → Files and folders. Also on the setup tour's search step.

{
  "fileSearch": false
}

fileSearchAlways

When true, every plain query of 2 or more characters also searches your home directory and adds up to 4 file rows. When false, files appear only for f:, file:, f invoice, file invoice, files invoice and path queries such as ~/Downloads/. It has no effect while fileSearch is false.

Type

boolean

Default

true

Set in panel

Search → Include files in every search, under Files and folders (disabled while that is off). Also on the setup tour's search step.

{
  "fileSearchAlways": false
}

clipboardSearch

Searches your clipboard history, so you can copy an earlier entry again with Enter. When false, there is no clipboard search at all, not even with cb:.

Type

boolean

Default

true

Set in panel

Search → Clipboard history. Also on the setup tour's search step.

{
  "clipboardSearch": false
}

clipboardSearchAlways

When true, every plain query of 2 or more characters also includes matching clipboard entries. When false, clipboard entries appear only for cb:, clipboard:, cb text, clip text and clipboard text. The hint under this toggle names the wrong prefix; the forms here are the ones that work. It has no effect while clipboardSearch is false.

Type

boolean

Default

true

Set in panel

Search → Include clipboard in every search, under Clipboard history. Not in the setup tour.

{
  "clipboardSearchAlways": false
}

learningEnabled

Moves the apps, windows, files and commands you pick often higher over time. Spotlight records only a plain Enter or click on those rows, never ShiftEnter, CtrlEnter or Shift-click. The data stays in ~/.local/state/omarchy/spotlight-usage.json and never leaves your machine.

When false, Spotlight stops recording and ignores what it learned, but keeps the file. The empty query then shows five apps and nothing else. To delete the data, use Reset learning data in the panel.

Type

boolean

Default

true

Set in panel

Search → Learn from your choices. Also on the setup tour's search step.

{
  "learningEnabled": false
}

Web

webSuggestions

Adds search suggestions as you type. Each query is sent to Kagi when searchEngine is "kagi", and to Google for every other engine, so this is off by default.

Suggestions need 2 or more characters and appear only in a plain search or under web:, search: or url:. Spotlight sends nothing for URLs, bangs, calculations, currency, reminders, events, file filters and path queries. It waits 220 ms after you stop typing, sends at most the first 200 characters, and gives up after 3 seconds. maxSuggestions sets how many rows appear.

Type

boolean

Default

false

Set in panel

Web → Search suggestions. Also on the setup tour's search step.

{
  "webSuggestions": true
}

searchEngine

The engine behind the web fallback row, Search <Engine> for “query”, which ends every plain or web: query that is not a URL. It also picks the suggestion provider: Kagi for "kagi", Google for everything else. Bangs such as gh spotlight always use their own engine.

Type

string

Default

"g" (Google)

Values

Any bang key from the table below, case-insensitive. "gg" and "google" also mean Google. Any other value means Google.

Set in panel

Web → Web search engine (a menu of 20 engines). Also on the setup tour's search step.

{
  "searchEngine": "ddg"
}

Currency

currencyRates

Fetches exchange rates from Frankfurter for complete currency queries such as 100 USD to EUR. Spotlight sends only the two currency codes and keeps each rate in ~/.cache/omarchy/spotlight-currency.json for 24 hours. When false, Spotlight uses cached rates only and never contacts the network.

Type

boolean

Default

true

Set in panel

Currency → Currency rates. Also on the setup tour's search step.

{
  "currencyRates": false
}

defaultCurrency

The target currency for a query that names no target, so 23 USD converts to it. An explicit target, as in 23 USD to JPY, always wins. Empty means no default.

Type

string

Default

""

Values

A 3-letter code that Frankfurter supports, such as "EUR". Case and surrounding spaces are ignored. Any other value means no default.

Set in panel

Currency → Default currency, a text field with the placeholder "None or USD". An unsupported code turns the field red and is not saved. Also on the setup tour's search step.

{
  "defaultCurrency": "EUR"
}

Results

maxResults

The most rows the list holds. It applies to every search, including f: and cb:, but not to system views. The web rows come last, so a query with many local matches can push the web fallback off the list.

Type

integer

Default

20

Values

8 to 50

Set in panel

Results → Results shown

{
  "maxResults": 30
}

maxApps

The most application rows a query can add. It does not limit the empty query.

Type

integer

Default

8

Values

3 to 24

Set in panel

Results → Applications shown

{
  "maxApps": 12
}

maxSuggestions

The most search suggestion rows shown when webSuggestions is on. 0 hides them.

Type

integer

Default

4

Values

0 to 8

Set in panel

Results → Search suggestions shown

{
  "maxSuggestions": 6
}

Setup

setupCompleted

Records that you finished or skipped the setup tour. While it is false or missing, the next open is a first run: if Spotlight has no shortcut yet and nothing else holds AltSpace, it binds that chord, and then it starts the tour. Finishing the tour, pressing Skip tour or pressing Esc sets it to true.

To see the tour again, set it to false or delete the key. That is also the only way to re-arm the automatic shortcut claim. Run Setup Tour in the results and Run setup tour in the panel show the tour without changing this key.

Type

boolean

Default

false

{
  "setupCompleted": true
}

Each answer names the cause first, then the fix. If nothing here matches, collect the logs below and report a bug.

Opening and the shortcut

omarchy-shell shell toggle io.github.maajix.spotlight '{}'

o.bind("ALT + SPACE", "Spotlight", "omarchy-shell shell toggle io.github.maajix.spotlight '{}'")

Results

System views

python3 ~/.config/omarchy/plugins/io.github.maajix.spotlight/bin/spotlight-helper docker

Settings file

python3 -m json.tool ~/.config/omarchy/spotlight.json

Collecting logs

Spotlight runs inside omarchy-shell, so its errors land in the shell's log. Follow it while you reproduce the problem:

journalctl --user -t omarchy-shell -f

If the interface looks stale after an update or an edit, restart the shell with omarchy restart shell and try again before you report it.

Report a bug

Open an issue at github.com/maajix/omarchy-spotlight/issues and include:

• the Spotlight version (the version field in ~/.config/omarchy/plugins/io.github.maajix.spotlight/manifest.json) and the output of omarchy-version
• the exact query you typed, what you expected and what Spotlight showed
• the relevant log lines or helper output, and a screenshot if it helps
• any settings you changed from the defaults

Spotlight has no account, no telemetry, no analytics and no background network service. Everything below happens on your machine unless the network section says otherwise.

What Spotlight stores

Spotlight writes these files, each owned by you:

The usage and currency files each have a small .lock file next to them. Settings are written atomically, so a crash never leaves a half-written file.

Learning data

When you open an app, window, file or command with Enter, Spotlight records it so it ranks higher next time. The file holds selection counts, timestamps, stable ids, file paths and the start of the queries you typed. Opening something with ShiftEnter or CtrlEnter is never recorded, and neither are system view rows.

• Turn off Learn from your choices in Spotlight Settings to stop recording and ignore what is stored. The file stays in place.
• Press Reset learning data twice to delete it. The panel confirms with "Learning data cleared".

See How search works and learningEnabled.

What Spotlight only reads

Clipboard search reads Omarchy's own history file, ~/.local/state/omarchy/clipboard-history.json, and uses text items only. Spotlight does not copy it anywhere. The tldr client keeps its pages in ~/.cache/tldr.

What reaches the network

Spotlight makes no request when it starts and never refreshes anything in the background. Requests happen only in these cases:

• Kagi suggestions are anonymous (no cookies). If Kagi fails, Spotlight shows nothing rather than asking Google.
• A failed suggestion request shows no suggestions and no error.
• With Currency rates off, Spotlight uses cached rates only and contacts no one. Same-currency pairs never need the network.
• Listing a view sends nothing, with one exception: docker: talks to the daemon of your active Docker context, which may be on another machine.
• Spotlight loads no icons, favicons or images from the network.

Spotlight builds each request address itself, so nothing you type can point it at another host. Requests do not follow redirects, identify themselves as Spotlight, give up after 3 seconds and cap the response size. See webSuggestions and currencyRates.

The helper script

The Spotlight interface does not read files, run system tools or open network connections itself. It asks a Python helper in the plugin folder (bin/spotlight-helper) to do it, one short-lived process per request, and gets one JSON reply back. That helper is the security boundary:

• Every command runs as an argument list, never through a shell.
• Values cannot be read as command options: SSH hosts must match a strict pattern, container ids must be hex, Bluetooth addresses must be MAC addresses, mount targets must be absolute paths and services are passed as --unit=NAME. Wi-Fi and audio names that start with - are never passed on, and copying uses wl-copy --.
• Wi-Fi and Bluetooth names with control characters are rejected, and every string Spotlight displays is length-limited.
• Files are opened without following symlinks and must be regular files you own that are not group- or world-writable. Each has a size limit, and parent directories are checked one by one. This covers your settings, the usage and currency files, bindings.lua and ~/.ssh/config.
• Each system tool gets an output limit and a deadline; at the deadline its whole process group is killed.
• View lists are fetched fresh each time you open Spotlight, late replies are discarded, and view rows are never learned or sent as suggestions.

Report a vulnerability

Do not open a public issue, discussion or pull request for a security problem. Report it privately through GitHub's private vulnerability reporting. If that is unavailable, open a public issue titled "Security contact request" with no details, and a private channel will be arranged.

Include as much of this as you can:

• what the vulnerability is and its impact
• the Spotlight version or commit, your Omarchy version and environment
• steps to reproduce or a minimal proof of concept
• whether it needs user interaction or non-default settings
• relevant paths, inputs, commands or settings, and logs with secrets removed

The maintainer aims to acknowledge reports within 7 days and coordinates disclosure with you. Fixes cover the latest release and main, so reproduce on the latest release when you can. Good-faith research on systems you own is welcome, and anonymous reports are fine. The full policy is in SECURITY.md in the repository.

Newest release first, starting at 1.5.0. To get the latest version, run omarchy plugin update io.github.maajix.spotlight.

1.6.2 2026-09-24

Fixed

• Change Theme and Change Background apply the selected theme or background. Contributed by @timothyvermeiren.
• Change Font opens Omarchy's font picker.

1.6.1 2026-09-23

Added

• A settings panel. Search spotlight settings and press Enter to change search sources, web, currency, result limits, the shortcut and learning data without editing a file. ShiftEnter or CtrlEnter on the result still opens spotlight.json. Contributed by @vleeuwenmenno.
• A setup tour started from the panel returns to the panel when it ends.
• Reset learning data asks for a second press and confirms with "Learning data cleared".
• A desktop notification, "Spotlight settings not saved", when a save fails after you closed the panel.

Changed

• "Edit Spotlight Settings" is now Spotlight Settings and opens the panel.

Fixed

• Settings are saved in order. A failed save is shown and waits for Retry save.
• spotlight.json opens for editing only after pending saves are written.
• The open panel refreshes from the settings that were actually saved.
• The setup tour is skipped when spotlight.json does not parse, and a finished tour is not resumed while its save is pending.
• Rows toggle with Space or a click only; Enter no longer toggles them. A click on a disabled option no longer toggles its row.
• The panel and each tour step open with nothing focused, and clicking a button no longer moves focus.
• Esc leaves the Default currency field.
• The search engine menu shows an aliased engine as selected, opens upward near the bottom of the screen and matches the tour's styling inside the tour.
• The ShiftEnter hint shows on the Spotlight Settings result.
• The examples on the last tour step are centered.

Removed

• The "Change Spotlight Shortcut" and "Reset Spotlight Learning" results. Use Change under Shortcut and Reset learning data under Maintenance in the panel.

1.6.0 2026-09-23

Added

• System views: ports:, ssh:, docker:, services:, mounts:, audio:, wifi: and bluetooth: list what is on your machine and act on the selected row.

Fixed

• Typing a view's full name selects the view, even when an app has that exact name. wifi and bluetooth now select their views; the toggles are the next rows down.
• Wi-Fi and Bluetooth names can no longer inject fake rows, and names with Unicode control characters are rejected.

1.5.4 2026-09-22

Added

• Currency conversions with rates from Frankfurter, cached for 24 hours and on by default. Only the two currency codes are sent. Contributed by @vleeuwenmenno.
• A default currency, so 23 USD converts without a target.
• New settings currencyRates and defaultCurrency.

1.5.3 2026-09-22

Added

• Kagi as a search engine. With Kagi selected, suggestions come from Kagi and never fall back to Google. Contributed by @vleeuwenmenno.

1.5.2 2026-09-21

Added

• CtrlC copies the path of the selected file result. Contributed by @brenoperucchi.

Changed

• The setup tour checks Hyprland's live bindings to see whether a shortcut is free, and says when it cannot tell. Contributed by @brenoperucchi.

Fixed

• Bindings that apply in every submap count as taken.
• An incomplete answer from Hyprland is no longer read as "free".

1.5.1 2026-09-20

Changed

• tldr example rows use the same copy action as other copyable results.

1.5.0 2026-09-20

Added

• Command help: tldr ssh, man ssh or man:ssh shows tldr examples for a command, grouped under their descriptions.

Spotlight is a plain Omarchy plugin: QML for the interface, JavaScript for parsing and ranking, and one Python helper for everything that touches files, system tools or the network. There is no build step.

Repository layout

Run from a local checkout

The installed plugin is already a git checkout of the repository, at ~/.config/omarchy/plugins/io.github.maajix.spotlight (the Open Spotlight Plugin Folder result opens it). Omarchy watches that folder and reloads Spotlight shortly after you save a file, so you can work there directly.

1. Fork the repository

   Fork maajix/omarchy-spotlight on GitHub. Keep origin pointing at the original repository, because omarchy plugin update pulls from it.

2. Create a branch

   Add your fork as a second remote and branch from main:

   cd ~/.config/omarchy/plugins/io.github.maajix.spotlight
   git remote add fork https://github.com/YOUR-USER/omarchy-spotlight.git
   git switch -c my-change

3. Edit and try it

   Save a file and open Spotlight to see the change. If the interface still looks old, restart the shell with omarchy restart shell.

4. Switch back before updating

   omarchy plugin update only fast-forwards. With local changes or commits it stops with "cannot fast-forward". Run git switch main with a clean tree first.

Run the checks

From the plugin folder, run these before you commit. They need python3, node and Qt 6's qmlformat.

omarchy plugin validate .
python3 -m unittest discover -s tests -p '*_test.py'
node --test
python3 -m py_compile bin/spotlight-helper
/usr/lib/qt6/bin/qmlformat -n *.qml >/dev/null
for file in lib/*.js; do node --check "$file"; done
git diff --check

The first line validates the manifest, the next two run the Python and JavaScript tests, and the rest catch syntax errors and stray whitespace. To run one test file, use node tests/currency.test.js.

CI runs the manifest check, the helper tests, node --test and the whitespace check on Python 3.14 and Node 24 for every pull request and push to main.

Contribute

1. Run the checks above, then commit your change on the branch.
2. Push the branch to your fork: git push fork my-change.
3. Open a pull request against main on GitHub. CI runs on it.

Report bugs and ideas on the issue tracker; see Report a bug for what to include. Never put a security problem in a public issue or pull request. Follow Report a vulnerability instead.

Design and security docs

• README.md in the repository is the feature reference, with the dependencies and the privacy table.
• SECURITY.md holds the security policy and design notes. It names the helper as the main boundary for file access and command execution, so issues there matter most.
• On this site, How search works covers parsing, ranking and learning, The helper script covers the hardening, and the Settings reference lists every key in spotlight.json.