EN | RU | CN | ID

Desktop Cat: QT Overlay 🐱

I made a cute little animated cat 🐈 for your desktop.
It's a lightweight Python + Qt app — no borders, and you can drag it around easily.
Shows static first frame for 5 seconds, then plays GIF animation once, then loops back to static.
If you like it, maybe I'll share an AnimeGirl version next time~ 😉

🚀 Quick start

Pick whichever is easiest — the cat runs on Windows, macOS and Linux.

Option A — prebuilt binary (no Python needed)

Download the build for your OS from the latest release, then run it:

OS	File	How to run
Windows	mycat-<version>-windows-x64.exe	double-click it
macOS	mycat-<version>-macos-arm64.zip	unzip, then open mycat.app

Builds for every release live on the Releases page.

Option B — pip (Windows / macOS / Linux, Python ≥ 3.10)

pip install mycat
mycat

On Linux also install the Qt platform plugin once:

sudo apt install -y libxcb-cursor0

Upgrade or remove later with pip install -U mycat / pip uninstall mycat.

Option C — from source

git clone https://github.com/yumiaura/myCat
cd myCat
pip install .
mycat                 # or, without installing:  python3 mycat/main.py

✨ Features

• Animated overlay 🐱 — a frameless, always-on-top, draggable cat. Right-click for the menu (switch skin, quit).
• Reminder 🛩️ — set a message and a time (one-shot or daily) and the cat flies a little banner plane across the top of your screen. Right-click → Reminder… to set the message, direction, plane and color.
• Chat (Ollama) 💬 — talk to the cat through a local Ollama model, no account or API key needed (see below).

💬 Chat with the cat (Ollama)

The cat can chat using a model served locally by Ollama — everything stays on your machine, no API key required.

1. Install Ollama and pull a model:

   ollama pull llama3.1

2. Launch mycat, then right-click the cat → Ollama…
3. Set the host/port (default localhost:11434), click Load models, pick one, hit Test, then Save and tick LLM enabled.
4. Right-click → Chat to start talking. 🐾

🎮 Usage & options

Run mycat (or python3 mycat/main.py from source) and customise it with command-line options.

--image, -i <path> 🖼️ — use a custom ZIP archive (containing one GIF) instead of the default cat:

mycat --image ~/my-custom-cat.zip

A skin ZIP must contain exactly one .gif: its first frame is the static pose, then the GIF plays once and returns to that frame. Images larger than 300×500 are scaled down automatically.

--pos <x> <y> 📍 — start at a specific screen position (otherwise the cat appears bottom-right and remembers where you last dragged it):

mycat --pos 960 540        # center of a 1920x1080 screen

--wait <seconds> ⏱️ — how long to hold the static first frame before the animation plays.

--debug 🐞 — verbose per-frame logging.

Controls

• Left-drag the cat to move it.
• Right-click the cat for the menu (skins, Reminder…, Ollama…, Chat, Quit).
• Quit from the menu or with Ctrl+C in the terminal.

The cat remembers its position and selected skin between sessions in ~/.config/mycat/config.ini.

🎬 Make your own cat GIF

# Install ImageMagick
sudo apt install imagemagick

# Build an animated GIF from a sprite sheet
convert images/cat.png -crop 50%x100% +repage -set delay '200,100' -loop 0 images/cat.gif

# Package it as a skin ZIP
zip images/cat.zip images/cat.gif

Drop the resulting ZIP next to the others and pick it from the right-click skins menu.

🐳 Docker

Run the cat in a container with GUI forwarding to your host's X server.

Prerequisites: Docker, and an X server on the host (Xorg on Linux, VcXsrv on Windows, XQuartz on macOS).

# Linux
xhost +local:docker
docker compose up --build

# Windows (VcXsrv running, network clients allowed)
docker compose -f docker-compose.windows.yml up

# macOS (XQuartz running, network clients allowed)
docker compose -f docker-compose.mac.yml up

🔧 Troubleshooting

Cat appears in a black box / transparency doesn't work 🫥

• On X11 transparency needs a compositor. mycat falls back to clipping the window to the cat's outline when none is running, so this is rare; if you still see a box, enable display compositing (XFCE: Window Manager Tweaks → Compositor) or run a compositor such as picom.

Window doesn't stay on top / doesn't show in the taskbar 📌

• Some window managers override "always on top" — restart the desktop session or check the WM settings.

Custom skin doesn't load ❌

• The ZIP must contain exactly one valid .gif. Check the path and that the file isn't corrupted.

Position not saving 💾

• Make sure ~/.config/mycat/ exists and is writable; the config file is ~/.config/mycat/config.ini.

Windows / launch issues 🪟

• Need Python ≥ 3.10 (python --version) for the pip install, or just use the prebuilt .exe.
• From the repo you can also launch with run.bat (Windows) or run.sh (Linux/macOS).
• Verify PySide6: python -c "import PySide6; print('PySide6 OK')".

Permission errors 🔒

• On Linux prefer a user install over sudo (pip install --user mycat).

🤝 Getting help

• Search the GitHub Issues for similar problems.
• Read CONTRIBUTING.md for development setup.
• Open a new issue with your OS, desktop environment, Python version and any terminal errors.

License

MIT License

Thank you for reading to the end! 😸🐾