keybind-audit

🔍 Detect and resolve keyboard shortcut conflicts across your entire Linux system.

Scans keybindings from fcitx5, tmux, GNOME/dconf, xbindkeys, i3, and more. Shows exactly which app claims each key and why conflicts happen.

Problem It Solves

You set Ctrl+Space as your tmux prefix, but fcitx5 intercepts it for input method switching. Result: tmux never sees the key. Which config do you edit? Where's the conflict coming from?

keybind-audit finds this automatically and tells you:

• Which apps claim the same key
• Which one actually wins (priority by layer)
• How to fix it

Installation

git clone https://github.com/hoornet/keybind-audit
cd keybind-audit
pip install -e .

Or just run directly:

python3 keybind_audit.py

Usage

Basic scan

keybind-audit

Output:

Scanning keybindings...
Found 42 unique keybindings.

⚠ Found 2 conflicting keybindings:

1. Ctrl+Space
   Claimed by 2 apps:
      [input-method    ] fcitx5          trigger-key                   ~/.config/fcitx5/config → ACTIVE
      [app             ] tmux           send-keys                      ~/.tmux.conf  
   ⚡ Takes precedence: fcitx5 (input-method)

Show all keybindings (verbose)

keybind-audit --verbose

Export as JSON

keybind-audit --json > conflicts.json

Get fix suggestions

keybind-audit --suggest-fixes

Scan a different home directory

keybind-audit --home /root

How It Works

Hierarchy (top = highest priority, hardest to override):

1. Compositor (Wayland/X11) - System level, gets key before apps
2. dconf (GNOME settings) - Desktop environment
3. input-method (fcitx5, ibus) - Input method framework
4. wm (i3, kwin) - Window manager
5. app (tmux, vim) - Application level
6. xbindkeys - Lowest priority, easiest to override

If fcitx5 (input-method layer) claims a key, it intercepts it before tmux (app layer) ever sees it.

Config Files Scanned

App	Config File	Level
fcitx5	~/.config/fcitx5/config	input-method
tmux	~/.tmux.conf	app
GNOME	dconf (via gsettings)	dconf
xbindkeys	~/.xbindkeysrc	xbindkeys
i3	~/.config/i3/config	wm

(More can be added easily)

Example: Fixing the Omarchy Issue

From the GitHub issue, the problem:

tmux prefix: Ctrl+Space (v3.4.0 default)
fcitx5 trigger: Ctrl+Space (hardcoded)
→ fcitx5 wins, tmux never sees the key

Run keybind-audit:

$ keybind-audit --suggest-fixes

For Ctrl+Space:
  Currently intercepted by: fcitx5 (input-method)
  To fix conflicts, remove/change in:
    • tmux: Edit ~/.tmux.conf
      Find: bind-key -n C-Space send-keys

Then fix it:

# Option 1: Change tmux prefix
echo "unbind-key -n C-Space" >> ~/.tmux.conf
echo "bind-key -n C-b send-keys" >> ~/.tmux.conf

# Option 2: Disable fcitx5 trigger
# Edit ~/.config/fcitx5/config, remove Control+space from [Hotkey/TriggerKeys]
pkill fcitx5 && fcitx5 -d

Extend It

Add your own app by calling the scan_* method pattern:

def scan_myapp(self) -> None:
    config_path = Path(self.home) / ".config/myapp/bindings"
    # Parse and call self.bindings[key].append({...})

Then add self.scan_myapp() to scan_all().

License

MIT

Author

Built by hoornet (@hoornet) & Clyde for the Omarchy Linux community

Contributing

Issues and PRs welcome: https://github.com/hoornet/keybind-audit