deskint

Turn a downloaded AppImage, archive or binary into a proper desktop app — with the right icon in the dock.

Right-click in Files  ->  Open With  ->  Add to Applications

---

Install

curl -fsSL https://raw.githubusercontent.com/jestink-dev/deskint/main/install.sh | bash

Or from a clone:

git clone https://github.com/jestink-dev/deskint.git && cd deskint
./install.sh

Then right-click any AppImage, .tar.gz or binary in your file manager and pick Open With → Add to Applications. Uninstall with ./install.sh --uninstall.

Screenshots

Coming — see docs/screenshots.md.

Why this exists

GNOME draws a generic gear in the dock when it cannot match a running window back to a .desktop file. Matching depends on StartupWMClass equalling the window's real WM_CLASS, which is very often not the app's name:

App	Actual WM_CLASS	Guess based on the name
Obsidian	md.Obsidian	✗
LM Studio	LM-Studio	✗ (it is hyphenated)
STM32CubeIDE	STM32CubeIDE	✗ (entry is stm32cubeide-2.2.0.desktop)

Existing tools (AppImageLauncher, Gear Lever) copy the StartupWMClass out of the AppImage's bundled .desktop file. That works — until the bundle doesn't declare one, which is common. deskint then launches the app briefly and reads WM_CLASS directly via xprop.

How it compares

Both of the tools above are good at what they do; deskint covers a different slice. Based on their public documentation — corrections welcome:

	deskint	AppImageLauncher	Gear Lever
AppImages	yes	yes	yes
Tarballs / zips / loose binaries	yes	—	—
StartupWMClass from the bundled .desktop	yes	yes	yes
StartupWMClass detected by launching the app	yes	—	—
Audits and repairs launchers it did not create	yes	—	—
Shipped as	one script, no daemon	deb/rpm + daemon	Flatpak
AppImage self-update handling	stable symlink	yes	yes

What it handles

• AppImages — reads bundled metadata, installs a stable symlink so a self-updating AppImage that renames itself can never orphan its launcher
• Archives — .tar.gz / .tar.xz / .tar.bz2 / .tar / .zip, unpacked into ~/Apps/<Name>/ with path-traversal ("zip slip") protection
• Loose binaries and app folders — including shell-script launchers

For each one it installs the icon into the hicolor theme at 48/64/128/256/512 px (so the shell picks a size instead of rescaling one bitmap), writes a spec-compliant entry, normalises Categories to a single main category, and refreshes the desktop and icon caches.

Usage

deskint FILE              # GUI assistant (also the "Open With" entry point)
deskint                   # manager window: what is installed, audit, remove

deskint --cli FILE        # headless
deskint --audit           # find broken icons / missing StartupWMClass
deskint --audit --fix     # repair what is safely repairable
deskint --list
deskint --remove ID       # entry + every icon size + cache refresh
deskint --set-default     # double-clicking an AppImage integrates it

--audit is useful on an existing system: it finds dangling icon symlinks, Icon= paths pointing at files that no longer exist, entries with duplicate main categories, and launchers whose window class cannot be matched.

All flags

Flag	What
--cli	run headlessly instead of opening the GUI
--list	list managed applications
--remove ID	remove an integration by id
--audit	scan for broken desktop entries
--fix	with --audit, repair what can be repaired
--no-move	leave the file where it is
--no-detect	skip launching the app to read WM_CLASS
--name NAME	override the application name
--install-handler	register deskint itself with the desktop
--set-default / --unset-default	make deskint the default for AppImages
--version	print the version

Requirements

Linux with a freedesktop-compliant desktop (developed on GNOME). Python 3.9+, python3-gi, gir1.2-gtk-4.0, gir1.2-adw-1, desktop-file-utils, and x11-utils for window-class detection. No other dependencies, no daemon, no packaging. install.sh checks for all of them and prints the right command for Debian/Ubuntu, Fedora and Arch.

Limitations

• Window-class detection is X11-only. xprop cannot see native Wayland windows. Under Wayland the step is skipped with a warning; everything else works. Most Electron and Qt apps still run under XWayland, where it works.
• Detection launches the app for up to 45 s and then terminates it. Apps that need a splash/login before opening a window may not be detected.
• --audit treats an entry named after its own binary as fine, because GNOME falls back to matching the filename. That is GNOME's documented behaviour but is an inference, not a per-app verification.

Layout

Path	What
~/.local/bin/deskint	core pipeline + CLI
~/.local/bin/deskint_gui.py	GTK4 / libadwaita front end
~/.local/share/applications/	generated .desktop entries
~/.local/share/icons/hicolor/	installed icons
~/Apps/<Name>/	installed applications

Generated entries are tagged X-Deskint-Managed=true, so --list and --remove never touch launchers deskint did not create.

Contributing

Bug reports and patches are welcome — see CONTRIBUTING.md. Window-class quirks for a specific app are especially useful: they are the whole reason this exists.

License

MIT © Jestin Kuriakose