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.

Since v0.13.1 the toggle checks that it owns that file before touching it. If an entry of that name is already there and is not one TypeWhisper wrote — you hand-edited it, or another tool created it — TypeWhisper leaves it alone and tells you ("left the foreign or customized autostart entry … untouched") rather than overwriting it on enable or deleting it on disable. The KDE shortcut integration applies the same ownership check to its own target.

Single-instance enforcement

TypeWhisper enforces a single instance using a Unix control socket under XDG_RUNTIME_DIR (since v0.13.1, falling back to a 0700 Runtime/ directory under the app's base path when XDG_RUNTIME_DIR is unavailable — the fallback used to be /tmp/typewhisper-$UID). 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.

When the local API is enabled it places a second socket, api.sock, in the same directory — that is the route typewhisper-cli uses. See HTTP API.

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.
2026-09-07	v0.13.1: autostart (and the KDE integration) now refuse to overwrite or delete an entry TypeWhisper does not own; noted the API socket beside the control socket and the socket fallback moving from /tmp to Runtime/ under the base path.