Desktop Integration

Desktop Integration

TypeWhisper integrates with your Linux desktop through a tray icon, XDG autostart, single-instance enforcement, and a user-level desktop launcher. This page describes those integration points and the environment variables that affect them.

Tray icon and close-to-tray

TypeWhisper provides a tray icon where the current desktop environment exposes a compatible system tray. The "close to tray" setting is gated on whether a real system tray is actually registered — detected via a D-Bus probe at startup — so the app can't hide itself with no way back to the UI.

On GNOME Wayland, tray icons need the AppIndicator extension. See Wayland notes for the install steps.

The tray icon is separate from the launcher/dock icon. When running from source with dotnet run, GNOME may not match the process to a registered desktop entry, so the dock or app switcher can show a generic icon. The desktop installer registers the .desktop file and icon theme entry for that case.

Autostart

TypeWhisper integrates with XDG autostart through ~/.config/autostart/typewhisper.desktop, so it can start with your session.

Single-instance enforcement

TypeWhisper enforces a single instance using a Unix control socket under XDG_RUNTIME_DIR (falling back to a 0700 directory under /tmp when XDG_RUNTIME_DIR is unavailable). A second launch hands its CLI command off to the already-running instance over a JSON control protocol, instead of starting a new window. See CLI for the commands a second launch can pass along.

Environment variables

Variable	Effect
TYPEWHISPER_DISABLE_IME=1	Disables Avalonia X11 IME integration when debugging input-method issues.

Desktop install script

The desktop install script publishes the app, installs it under the user profile, and creates a launcher icon. See Installation for the full install and uninstall steps.

Related pages

• Installation — install formats and the desktop install script.
• CLI — the control commands handed to a running instance.
• Wayland notes — GNOME tray icon setup and other Wayland specifics.

---

Changelog

Date	Change
2026-06-17	Initial version.