mycat 0.1.16

Desktop Cat: Qt Overlay

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~ 😉

LLM Chat, Reminders, GitHub Integration & Tracking Activity

🚀 Quick start

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

Option A - prebuilt binary (no Python needed)

Grab the build for your OS - each button downloads the latest release:

Then run it:

• Windows - double-click the .exe.
• macOS - unzip and open mycat.app (first launch: right-click → Open to get past Gatekeeper).
• Linux .deb - sudo apt install ./mycat-linux-amd64.deb.
• Linux AppImage - chmod +x mycat-linux-x86_64.AppImage && ./mycat-linux-x86_64.AppImage (needs FUSE: sudo apt install libfuse2).

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

The activity diary can count key presses and clicks (never which keys) - it works out of the box on Windows, macOS and Linux/X11. Where global input access isn't available (e.g. Wayland) it degrades to recording the cursor path.

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 char, 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 char 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 (Chars, Reminder…, Ollama…, Chat, Quit).
• Quit from the menu or with Ctrl+C in the terminal.

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

🎬 Make your own cat

A char is just an animated GIF in a .zip - from a quick doodle to a fully interactive cat with cursor-tracking eyes, blinking, sleeping and click reactions. Step-by-step guide (draw it, build the GIF, package, install & share): docs/CHARS.md.

🐳 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 char 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! 😸🐾