ShortcutCounter

Passive keyboard shortcut tracker for Linux/Wayland. Runs as a background daemon, records only modifier+key combinations (e.g. Ctrl+C), and shows usage stats via CLI or the ClaudeCodePanel tab.

Installation

# 1. Install dependencies
pip install evdev click rich

# 2. Add yourself to the input group (required for evdev access)
sudo usermod -aG input $USER
# Log out and back in for the group change to take effect

# 3. Install the package
pip install -e .

Usage

# Start the daemon in the background
shortcut-counter start

# Start in foreground (for debugging)
shortcut-counter start --foreground

# Stop the daemon
shortcut-counter stop

# Check daemon status
shortcut-counter status

# Show all tracked shortcuts with counts
shortcut-counter stats

# Show top 10 most used shortcuts
shortcut-counter top

# Show top N (e.g. top 5)
shortcut-counter top 5

# Show shortcuts from config that you've never used — learn these!
shortcut-counter learn

# Show shortcuts used today
shortcut-counter today

Konfiguration

Shortcuts are defined in config.toml. The file is loaded from:

1. ~/.config/shortcut-counter/config.toml (user config)
2. config.toml in the project directory (fallback for development)

Format:

[shortcuts]

[shortcuts.Editing]
combos = [
    "Ctrl+C",       # Kopieren
    "Ctrl+V",       # Einfuegen
    "Ctrl+Z",       # Rueckgaengig
]

[shortcuts.Terminal]
combos = [
    "Ctrl+Shift+C", # Kopieren im Terminal
    "Ctrl+Shift+T", # Neues Tab
]

Valid modifiers: Ctrl, Alt, Shift, Super

To add a custom category, add a new [shortcuts.MyCategory] section with a combos list.

Panel-Integration

The ClaudeCodePanel has a ShortcutCounter tab at: ~/Projekte/ClaudeCodePanel/shortcut_counter_tab.py

It shows a read-only live view of shortcut statistics within the GTK3 panel.

systemd Service

To run the daemon automatically on login:

# Create service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/shortcut-counter.service << 'EOF'
[Unit]
Description=Shortcut Counter Daemon
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 -m shortcut_counter.daemon
Restart=on-failure

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user enable shortcut-counter
systemctl --user start shortcut-counter

# Check status
systemctl --user status shortcut-counter

# Stop
systemctl --user stop shortcut-counter

Privacy

Only modifier+key combos are tracked (e.g. Ctrl+C, Alt+Tab). Individual keystrokes, letters, and text are never recorded. All data stays local in ~/.local/share/shortcut-counter/shortcuts.db.