QimoBar - Desktop Pet / GIF Widget

A lightweight, cross-platform desktop GIF companion app

English | 简体中文

Built with Tauri 2 + React + TypeScript + Rust.

Features

• System tray / menu bar integration (macOS menu bar, Windows system tray)
• Transparent, borderless pet window that floats on your desktop
• Drag to move the pet anywhere on screen
• Import GIF from local files via file dialog
• Position memory - pet remembers where you left it
• Scale and opacity controls
• Click-through mode - let clicks pass through the pet window
• Always on top toggle
• Launch at startup support
• Multi-monitor awareness - pet stays visible when monitors change
• Single instance enforcement
• Settings panel with real-time preview
• Multiple GIF assets - import and switch between different pets

Prerequisites

• Node.js >= 18
• Rust >= 1.70
• Platform-specific:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Microsoft C++ Build Tools, WebView2

Quick Start

# Install dependencies
npm install

# Run in development mode (hot reload)
npm run tauri dev

# Build for production
npm run tauri build

Build Output

After npm run tauri build:

• macOS: src-tauri/target/release/bundle/macos/QimoBar.app and .dmg
• Windows: src-tauri/target/release/bundle/msi/ and nsis/

Project Structure

QimoBar/
├── src/                      # React frontend
│   ├── pages/
│   │   ├── PetWindow.tsx     # Pet display + drag + GIF rendering
│   │   └── SettingsWindow.tsx # Settings UI panel
│   ├── types/index.ts        # TypeScript type definitions
│   ├── App.tsx               # Route-based page selector
│   ├── main.tsx              # React entry point
│   └── styles.css            # All styles
├── src-tauri/                # Rust backend
│   ├── src/
│   │   ├── lib.rs            # App setup, plugins, command registration
│   │   ├── main.rs           # Binary entry point
│   │   ├── tray.rs           # System tray / menu bar
│   │   ├── window.rs         # Pet window creation + monitor safety
│   │   ├── config.rs         # Config & asset persistence (JSON)
│   │   └── commands.rs       # IPC commands
│   ├── Cargo.toml
│   └── tauri.conf.json
├── docs/
│   └── app-icon.png          # App icon used in docs
├── index.html
├── package.json
└── vite.config.ts

Configuration

Config stored at:

• macOS: ~/Library/Application Support/QimoBar/
• Windows: %APPDATA%/QimoBar/

Files:

• config.json - App settings (scale, opacity, position, etc.)
• assets.json - Imported GIF asset registry
• assets/ - Copied GIF files

Implemented Features (MVP)

• System tray / menu bar with right-click menu
• Show/Hide pet toggle
• Import GIF via file dialog
• Settings panel (scale, opacity, click-through, always-on-top, autostart)
• Quit from tray
• Transparent, borderless pet window
• Drag to move
• Position persistence & restore
• Scale control (0.3x - 3x)
• Opacity control (10% - 100%)
• Click-through toggle
• Always on top toggle
• Launch at startup
• Multi-monitor boundary check (falls back to center)
• Position reset
• Multiple GIF asset management (import, switch, delete)
• Single instance enforcement
• GIF validation (magic bytes + 50MB size limit)
• Config persistence (JSON)
• Visibility state persistence

Not Yet Implemented

• Drag-and-drop GIF import onto pet window
• Clipboard GIF import
• WeChat source import
• Cloud asset library
• Multiple pet instances
• Auto-wander / path animation
• Sound effects
• Auto-update

Known Issues

1. macOS transparent windows require macos-private-api flag
2. Pet window is fixed at 200x200px; large GIFs are scaled to fit
3. Position saved in physical pixels; display scaling changes may cause slight drift
4. When click-through is enabled, you must use the tray menu or settings to disable it

License

MIT