Mascots

Animated desktop companion that follows your cursor, attaches to windows, and reacts to your environment.

What is Mascots?

Mascots is a GPU-accelerated desktop overlay that renders an animated companion character on your screen. The mascot follows your cursor with smooth animations, blinks naturally, and reacts when you hover over specific windows. You can drag it around, attach it to windows, and customize its behavior.

Key Features:

• GPU-accelerated rendering - Custom WGSL shaders via wgpu (Vulkan/GL)
• Smooth cursor tracking - Exponential smoothing with velocity-based effects
• Drag animations - Squash/stretch on pickup, bounce on placement, tilt while moving
• Eye tracking - Eyes follow the cursor, natural blinking
• Window reactions - Detects terminals and other windows with configurable patterns
• Window attachment - Shift+click to attach mascot to a specific window
• Wayland native - Layer-shell support for proper overlay behavior
• X11 fallback - Works on X11 too
• Tmux awareness - Monitors tmux sessions and reacts to pane changes
• Extensible - Provider trait for custom AI integration and behaviors

Quick Start

Installation

# Using Cargo
cargo install mascots

# Or build from source
git clone https://github.com/0xPD33/mascots
cd mascots
cargo build --release
./target/release/mascots

Usage

Just run it:

mascots

The mascot appears and starts following your cursor.

Interactions:

• Click on mascot - Pick it up (starts following cursor)
• Click again - Put it down at current position
• Shift+click while dragging - Attach to window under cursor (KDE/KWin)
• Drag quickly - Mascot tilts in direction of movement

CLI Options:

mascots --help
mascots --verbose          # Enable debug logging
mascots --platform wayland # Force Wayland backend
mascots --platform x11     # Force X11 backend
mascots --config path.toml # Use custom config file

Configuration

Config file location:

• Linux: ~/.config/mascots/config.toml

Example Configuration

[appearance]
scale = 0.5              # Size multiplier (default: 0.5)
glow_intensity = 0.5     # Glow effect intensity 0.0-1.0

[behavior]
smoothing = 10.0                  # Cursor following smoothness (higher = snappier)
hover_transition_speed = 5.0      # How fast excitement ramps up/down

[terminal_detection]
enabled = true
additional_patterns = ["my-custom-terminal"]  # Add your terminal
excluded_patterns = []                         # Exclude false positives

[advanced]
frame_rate = 0           # 0 = vsync, otherwise target FPS
multi_monitor = "all"    # "all", "primary", or "cursor"

Built-in Terminal Detection

Automatically detects these terminals:

• alacritty, kitty, wezterm, foot
• gnome-terminal, konsole, xterm, urxvt
• st, terminator, tilix, hyper, tabby
• iterm2, terminal (macOS), warp

Platform Support

Platform	Backend	Status
Linux (Wayland)	layer-shell via winit	Full support
Linux (X11)	Override-redirect window	Basic support
macOS	-	Not yet implemented
Windows	-	Not planned

Wayland Compositors

Tested on:

• KDE Plasma (KWin) - Full support including window picker
• Hyprland - Should work (layer-shell)
• Sway - Should work (layer-shell)

Note: Window attachment (Shift+click) currently requires KWin's D-Bus interface.

AI Integration

Mascots can watch your terminal and provide brief, contextual commentary using AI. It also supports direct chat via right-click menu.

Supported Providers

Provider	Environment Variable	Default Model
Claude (Anthropic)	ANTHROPIC_API_KEY	claude-sonnet-4
OpenRouter	OPENROUTER_API_KEY	anthropic/claude-sonnet-4

Configuration

[ai]
enabled = true
provider = "claude"  # or "openrouter"
model = ""           # empty = use default

Features

• Terminal commentary - Watches tmux sessions for errors, test results, build status
• Direct chat - Right-click mascot to open chat input
• Mood-aware - Commentary reflects detected activity (errors, success, etc.)

Building

Dependencies

Core:

• Rust nightly (for some wgpu features)
• wgpu 24 (Vulkan/GL)
• winit with layer-shell support

Wayland:

• smithay-client-toolkit
• wayland-client libraries

X11 (optional):

• x11rb
• libxcb

Build Commands

# Build with all features
cargo build --release

# Build Wayland-only
cargo build --release --no-default-features --features wayland

# Build X11-only
cargo build --release --no-default-features --features x11

Troubleshooting

"No display server detected"

Set the appropriate environment variable:

export WAYLAND_DISPLAY=wayland-0  # For Wayland
export DISPLAY=:0                  # For X11

Mascot not visible

Check if your compositor supports layer-shell (wlr-layer-shell-unstable-v1).

Window picker not working

Window picker requires KWin's D-Bus interface. On other compositors, manual positioning is available.

Poor performance

Try forcing a different GPU backend:

WGPU_BACKEND=vulkan mascots
WGPU_BACKEND=gl mascots

License

MIT - See LICENSE for details.

Contributing

Built by 0xPD33

Issues and PRs welcome at https://github.com/0xPD33/mascots