Bongo Cat Wayland Overlay

A cute Wayland overlay that shows an animated bongo cat reacting to your keyboard input.

Features

🎯 Real-time keyboard animation
🔥 Hot-reload configuration
🎮 Auto-hides in fullscreen apps
🖥️ Multi-monitor support
😴 Idle/scheduled sleep mode
🎨 SVG-based rendering (pixel-perfect at any size)
⚡ Lightweight (~8MB RAM)

Quick Start

Install

# Arch Linux
yay -S bongocat

# Other distros - build from source
git clone https://github.com/saatvik333/wayland-bongocat.git
cd wayland-bongocat && make

Setup Permissions

sudo usermod -a -G input $USER
# Log out and back in

Find Your Keyboard

bongocat-find-devices  # or ./scripts/find_input_devices.sh

Run

bongocat --watch-config
# Optional: force one monitor from CLI
bongocat --watch-config --monitor eDP-1

Configuration

Create ~/.config/bongocat/bongocat.conf:

# ═══════════════════════════════════════════════════════════════════════════
# BONGO CAT CONFIG - Minimal defaults, uncomment to customize
# ═══════════════════════════════════════════════════════════════════════════

# Position & Size
cat_height=110
cat_align=center
# cat_x_offset=0
# cat_y_offset=0

# Appearance
overlay_height=120
overlay_opacity=0
overlay_position=bottom
# mirror_x=0
# mirror_y=0

# Input device (run bongocat-find-devices to find yours)
# Optional: keyboard_device=/dev/input/by-id/YOUR-KEYBOARD-event-kbd

# Multi-monitor (comma-separated monitor names)
# monitor=eDP-1,HDMI-A-1

# Sleep mode (optional)
# idle_sleep_timeout=300
# enable_scheduled_sleep=0
# sleep_begin=22:00
# sleep_end=06:00

Options Reference

Click to expand all options

Option	Values	Default	Description
`cat_height`	10-200	40	Cat size in pixels
`cat_align`	left/center/right	center	Horizontal alignment
`cat_x_offset`	any int	100	Horizontal offset from alignment
`cat_y_offset`	any int	10	Vertical offset from center
`enable_antialiasing`	0/1	1	Deprecated — no-op with SVG
`overlay_height`	20-300	50	Overlay bar height in pixels
`overlay_opacity`	0-255	150	Background opacity (0=transparent)
`overlay_position`	top/bottom	top	Screen edge position
`layer`	background/bottom/top/overlay	top	Wayland layer type
`keyboard_device`	/dev/input/path	auto	Specific evdev device to monitor
`keyboard_name`	string	—	Match device by name (for hotplug)
`monitor`	comma list	auto	Monitors to render on
`fps`	1-120	60	Animation frame rate
`mirror_x`	0/1	0	Flip cat horizontally
`mirror_y`	0/1	0	Flip cat vertically
`enable_hand_mapping`	0/1	1	Map keys to left/right hand frames
`keypress_duration`	ms	100	How long key-down frame is held
`idle_frame`	0-4	0	Frame shown when idle
`idle_sleep_timeout`	seconds	0	Sleep after idle (0=disabled)
`hotplug_scan_interval`	seconds	30	Device rescan interval (0=once)
`enable_scheduled_sleep`	0/1	0	Enable time-based sleep schedule
`sleep_begin`	HH:MM	00:00	Sleep schedule start time
`sleep_end`	HH:MM	00:00	Sleep schedule end time
`disable_fullscreen_hide`	0/1	0	Keep overlay visible in fullscreen
`enable_debug`	0/1	0	Enable debug logging
`test_animation_duration`	ms	200	Test animation frame duration
`test_animation_interval`	seconds	0	Test animation repeat interval

Monitor selection and appearance are reconciled during reload. Named outputs that are disconnected wait for reconnection; automatic selection uses the first available output. --monitor NAME remains a startup override.

Use [monitor:NAME] for appearance overrides and [global] to return to global settings. Global defaults apply before overrides regardless of section order. Supported overrides: cat_height, overlay_height, overlay_opacity, cat_x_offset, cat_y_offset, layer, overlay_position, cat_align, mirror_x, mirror_y, enable_antialiasing, and disable_fullscreen_hide. Input selectors and animation timing remain global.

monitor=eDP-1,HDMI-A-1
cat_height=40
[monitor:HDMI-A-1]
cat_height=60
mirror_x=1
[global]
fps=60

Startup tolerates malformed entries with warnings. Reloads and --check-config are strict: invalid, missing, or unreadable files leave the running config active. Watching tracks the parent directory, including atomic replacements, and reloads 300 ms after the final relevant event.

Command Line

bongocat [OPTIONS]

  -c, --config FILE    Config file path (default: auto-detect)
  -m, --monitor NAME   Force specific monitor output
  -w, --watch-config   Auto-reload on config change
  -t, --toggle         Start/stop toggle
  --check-config      Validate config without Wayland or input access
  --list-devices      List devices, capabilities and access errors
  --list-monitors     List monitor names, dimensions and scales
  --doctor            Check config, protocols, outputs and input permissions
  --hide / --show     Change visibility of every overlay
  --pause / --resume  Show idle frame, discard input, or resume animation
  --reload / --status Reload config or query the running instance
  -h, --help           Help
  -v, --version        Version

Controls use a user-owned Unix socket and require the same UID. Hide preserves animation state; pause displays the configured idle frame and discards input. Resume clears pending paw activity. Hidden and paused state reset on restart; controls never rewrite config files. Failed commands return nonzero.

When both input paths and names are empty, accessible keyboard-capable evdev devices are selected automatically. Explicit selectors never fall back to an unrelated device. Stable /dev/input/by-id/ and /dev/input/by-path/ aliases are supported and devices are deduplicated by identity. No permission changes are made automatically. Keycodes are never transmitted or logged, including with enable_debug=1.

Troubleshooting

Permission denied on input device

sudo usermod -a -G input $USER
# Then log out and back in

Cat not responding to keyboard

Run bongocat-find-devices to find correct device
Update keyboard_device in config
Restart bongocat

Not showing on correct monitor

Set monitor=YOUR_MONITOR (single) or monitor=MON1,MON2 (multi) in config. Find names with wlr-randr or hyprctl monitors.

Building

git clone https://github.com/saatvik333/wayland-bongocat.git
cd wayland-bongocat
make          # Release build
make debug    # Debug build

Requirements: wayland-client, gcc/clang, make

License

MIT License - see LICENSE

wayland-bongocat