Basically KurtVelasco's Desktop Gremlin, but re-written in PySide + Qt6.
output.mp4
💥 Features 💥
- Works on both X11 (with picom) and Hyprland (with XWayland).
- Also works on Windows and MacOS (follow the manual installation guide).
- Interactive controls:
- Drag & Drop: 🖱️ Click and drag your gremlins to move 'em.
- Walk: ⌨️ Hover your mouse over the gremlins, then use W/A/S/D to make 'em skedaddle 💨💨.
- Secret Moves: Right-click on different spots to play special animations 😎! It might be a headpat, a poke, or something even more special!
- Also, if you leave the gremlins lonely for so long, they will occasionally make more ✨noises✨ to annoy you 😈😈. Think of it as "1 hour of silence occasionally broken up by Mambo".
Note: The "1 hour of silence occasionally broken up by Mambo" feature can be turned off (if you are a chicken 🐔🐔). See Customizations.
- Run install script:
curl -s https://raw.githubusercontent.com/iluvgirlswithglasses/linux-desktop-gremlin/refs/heads/main/install.sh | bash- Call the gremlins from your app launcher!
Wanna tweak details, or install on a setup where the install script can't automate everything? Follow these steps to get your gremlins up and running exactly the way you want:
- 1. Configure your compositor
- 2. Install this repository
- 3. Choose your gremlins!
- 4. Run desktop gremlins!
- 5. Customizations
- 6. Create your gremlins!
- 2026-02-08 Breaking Change: Assets have been moved to release tags! If you have cloned this repo earlier than that, please see Migration Guide to avoid re-downloading the assets after
git pull. Also, take a look at the New Downloader! It helps downloading new gremlin assets with ease!
See 2025 changelog
- 2026-01-15: Refactored the entire codebase for modularity and strict type-check. Some behaviors have changed, some are intentional, some are bugs.
- 2026-01-14: Added Qt6 character selector GUI! Huge thanks to @Multex!
- 2025-11-18: Massive source code restructure! We now have a unified run script and a package recipe for Guix. (Huge thanks to @thanosapollo! This chad is a much better programmer than I am.)
- 2025-11-16: Added a manual trigger for the annoy emote. Press
Pto make them noisy on command. - 2025-11-15: Remapped headpats from Left Click to Right Click. No more accidental pats when you want to drag them around!
This is not a strict 1:1 port, because I made some changes to the animation flow to better match my own preferences. I also created a few additional spritesheets; please feel free to use them if they're helpful.
Starting 2026-02-08, assets have been move to release tags, which means contributors who submit assets via PRs would no longer appear in the GitHub contributors list 😢.
Therefore, if you'd like to contribute a new gremlin, please make two Pull Requests:
- The Asset PR: Submit your new asset to the
./gremlinsdirectory. This PR won't be merged, but it'll send me the asset. - The Credit PR: Add yourself to the glorious table below so the world knows of your deeds!
| Gremlin Asset | Contributor |
|---|---|
| Agnes Tachyon | @TRKako |
| Manhattan Cafe | @TRKako |
| Calstone Light | @virtualspan |
| Dream Journey | @virtualspan |
| Durandal | @virtualspan |
| Gold Ship | @TRKako |
| Haru Urara | @TRKako |
| Meisho Doto | @TRKako |
| Oguri Cap | @TRKako |
| T.M. Opera O | @TRKako |
| Stay Gold | @virtualspan |
| Tamamo Cross | @virtualspan |
| Tachibana Hikari | @Xgameisdabest |
| Kurosaki Koyuki | @Xgameisdabest |
| Exusiai | @virtualspan |
| Exusiai (with gun) | @virtualspan |
| Speaki | @Quicksilver151 |
A massive, heartfelt thank you to our incredible asset contributors!
There are some forks of this repository that you may want to checkout!
- #23: Significantly reduces memory usage of the app, though some functionalities will be different.