Gpotlight

Gpotlight is a Spotlight-style launcher for GNOME 50 on Wayland, built with Rust, GTK4, and libadwaita.

The app uses a large transparent GTK window as a centered container. GNOME centers that window, while the visible launcher surface is rendered near the upper center inside it. This avoids compositor-specific positioning hacks on Wayland.

Current Architecture

• GTK4/libadwaita UI with a transparent host window and visible launcher panel.
• Config file stored under $XDG_CONFIG_HOME/gpotlight/config.toml.
• Plugin registry with built-in plugins and an extension point for external plugins.
• Global shortcut portal adapter for org.freedesktop.portal.GlobalShortcuts.
• Status notifier tray entry for opening settings and toggling the launcher.
• Lightweight i18n resources in app/resources/locale.

Build

cargo build

Runtime dependencies expected on GNOME:

• GTK 4
• libadwaita
• A StatusNotifierItem/AppIndicator shell extension if your GNOME session does not show tray icons by default

Run

cargo run

Toggle a running instance without starting a new UI:

gpotlight toggle

To use a global keyboard shortcut, create a custom shortcut in GNOME Settings and set its command to:

gpotlight toggle

Open settings in a running instance without starting a new UI:

gpotlight settings

For GNOME portal permissions when running a debug build manually, install the desktop entry after copying the binary to a directory on your PATH:

install -Dm755 target/debug/gpotlight ~/.local/bin/gpotlight
install -Dm644 data/io.github.gpotlight.Gpotlight.desktop ~/.local/share/applications/io.github.gpotlight.Gpotlight.desktop
update-desktop-database ~/.local/share/applications

RPM

Build a Fedora RPM:

./scripts/build-rpm.sh

The package is written under target/rpmbuild/RPMS/.

Plugin Manifests

External plugins can be placed in either:

• plugins/*.toml during development
• /usr/share/gpotlight/plugins/*.toml for package-installed plugins
• $XDG_CONFIG_HOME/gpotlight/plugins/*.toml for user-installed plugins

Each plugin is a command that receives the query and prints JSON lines:

id = "example.web"
name = "Example Web Plugin"
description = "Searches a custom service"
command = "my-gpotlight-plugin"
args = ["--query", "{query}"]

[[config]]
key = "safe_mode"
title = "Safe mode"
description = "Filter potentially noisy results"
type = "bool"
default = true

[[config]]
key = "endpoint"
title = "Endpoint"
type = "text"
default = "https://example.com"

[[config]]
key = "provider"
title = "Provider"
type = "choice"
default = "primary"
options = [
  { value = "primary", label = "Primary" },
  { value = "backup", label = "Backup" },
]

Each output line should look like:

{"title":"Result","subtitle":"Details","icon":"system-search-symbolic","pinned":false,"action":{"type":"open-uri","uri":"https://example.com"}}

Gpotlight-owned plugin settings are configured in the settings window. Every plugin can be shown directly in global search or gated behind a trigger prefix such as / or {. External plugin custom settings are passed to the plugin process as JSON in GPOTLIGHT_PLUGIN_CONFIG.