wayland-bongocat

Bongo Cat Wayland Overlay

A Wayland overlay with a bongo cat that plays along with your keyboard.

• Reacts to every keyboard instantly, including keyboards plugged in later
• Follows the focused monitor, or stays on the monitors you name
• Hides under fullscreen windows
• Idle and scheduled sleep
• SVG artwork, sharp at any size and scale
• Live configuration reload

Requires a compositor with wlr-layer-shell (Sway, Hyprland, Niri, river, Wayfire and others).

Quick Start

# Arch Linux
yay -S bongocat

# From source
git clone https://github.com/saatvik333/wayland-bongocat.git
cd wayland-bongocat && make && sudo make install

Reading keyboards needs access to /dev/input:

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

Run it:

bongocat --watch-config

Every keyboard is used by default. bongocat --list-devices shows each input device, marks keyboards, and prints keyboard_name= and keyboard_device= lines you can paste into the configuration to pick specific ones. bongocat --doctor checks the configuration, device access and compositor support at once.

Configuration

The configuration is read from $XDG_CONFIG_HOME/bongocat/bongocat.conf, ~/.config/bongocat/bongocat.conf or ./bongocat.conf, or from -c FILE. Every setting is optional; bongocat.conf.example documents each one. For example, a large cat at the bottom of the screen:

cat_height=110
overlay_height=120
overlay_opacity=0
overlay_position=bottom
cat_x_offset=0
cat_y_offset=0

Monitors

Without monitor=, one cat follows the focused monitor. Focus comes from the wlr-foreign-toplevel-management protocol, or on Niri from its event stream, which also reports monitors showing an empty workspace. Without focus information the cat stays where it is. follow_active_monitor=0 keeps it on the first monitor instead. monitor=eDP-1,HDMI-A-1 or --monitor eDP-1 shows a cat on each named monitor, waiting for disconnected ones. Find names with bongocat --list-monitors.

[monitor:NAME] sections override the appearance settings, from cat_height to disable_fullscreen_hide in the table, for one monitor. [global] returns to global settings:

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

Fullscreen

A cat hides while the window most recently focused on its monitor is fullscreen, even when focus moves to another monitor. Switching that monitor to an empty workspace shows it again; Niri reports where the empty workspace is, other compositors are assumed to switch the monitor that had focus. The overlay layer and disable_fullscreen_hide=1 always stay visible.

Reloading

With --watch-config, saving the file reloads it, including atomic replacements and symlink changes; bongocat --reload does the same on demand. Startup skips invalid lines with a warning. Reloads and --check-config are strict: any invalid line keeps the running configuration.

Command Line

bongocat [OPTIONS]
  -c, --config FILE    Configuration path (searched by default)
  -w, --watch-config   Reload when the configuration changes
  -m, --monitor NAME   Show the cat only on this monitor
  -t, --toggle         Stop the running cat, or start one
  --hide, --show       Hide or show every overlay
  --pause, --resume    Show the idle frame and ignore input, or resume
  --reload, --status   Reload or describe the running cat
  --check-config       Strictly validate the configuration
  --list-devices       List input devices and keyboard settings
  --list-monitors      List monitors, sizes and scales
  --doctor             Check configuration, devices and compositor support
  -h, --help           Show help
  -v, --version        Show version

Only one cat runs per user. Control commands talk to it over a socket in $XDG_RUNTIME_DIR that only the same user can use; hidden and paused states reset when it restarts.

Troubleshooting

• Permission denied on input devices: add yourself to the input group as shown above, then log in again. bongocat --list-devices shows which devices are inaccessible.
• Cat ignores the keyboard: check bongocat --status for the device count, and that any keyboard_device/keyboard_name match your keyboard.
• Cat on the wrong monitor: set monitor= to a name from bongocat --list-monitors.
• Cat over fullscreen windows: use a layer other than overlay.

Building

make                  # Release build: build/bongocat
make debug            # AddressSanitizer and UBSan build
make test             # Unit tests
make test-runtime     # Tests against a private compositor; needs
                      # wayland-server, wayland-scanner and python3
sudo make install     # PREFIX=/usr/local by default; DESTDIR supported

Requirements: wayland-client, make and a C23 compiler. CC, CFLAGS and LDFLAGS are honored. See ARCHITECTURE.md and CONTRIBUTING.md.

License

MIT License - see LICENSE