PowerKit keybinding system and conflict resolution.

PowerKit registers these default keybindings:

Plugins may register additional keybindings:

Note: Keybindings using M- (Meta/Alt) require terminal configuration on macOS. See macOS Alt Key Setup.

Change default keybindings in tmux.conf:

# Global keybindings
set -g @powerkit_options_key "C-o"
set -g @powerkit_keybindings_key "C-k"
set -g @powerkit_theme_selector_key "C-t"

# Plugin keybindings
set -g @powerkit_plugin_bitwarden_keybinding_password "C-p"
set -g @powerkit_plugin_pomodoro_keybinding_toggle "C-m"

PowerKit detects conflicts with existing tmux keybindings at startup.

Configure how conflicts are handled:

# warn: Show notification, still bind (default)
set -g @powerkit_keybinding_conflict_action "warn"

# skip: Don't bind if conflict exists
set -g @powerkit_keybinding_conflict_action "skip"

# force: Override existing binding
set -g @powerkit_keybinding_conflict_action "force"

When warn is set, a toast notification shows conflicting keys at startup.

Press prefix + C-y to open the keybindings viewer, which shows:

• All PowerKit keybindings
• Conflicting bindings
• Current assignments

On macOS, the Option key doesn't work as Meta/Alt by default in most terminal emulators. You need to configure your terminal to use Option as Alt/Meta for M- keybindings to work.

Add to your Ghostty config (~/.config/ghostty/config):

macos-option-as-alt = true

1. Go to Preferences → Profiles → Keys
2. Set Left Option Key to Esc+
3. Set Right Option Key to Esc+ (optional)

Add to your Alacritty config (~/.config/alacritty/alacritty.toml):

[window]
option_as_alt = "Both"  # or "OnlyLeft" / "OnlyRight"

Add to your Kitty config (~/.config/kitty/kitty.conf):

macos_option_as_alt yes

Add to your WezTerm config (~/.wezterm.lua):

return {
  send_composed_key_when_left_alt_is_pressed = false,
  send_composed_key_when_right_alt_is_pressed = false,
}

1. Go to Terminal → Settings → Profiles → Keyboard
2. Check Use Option as Meta key

If you prefer not to change terminal settings, configure PowerKit to use C- (Ctrl) keybindings instead:

# Use Ctrl instead of Meta for audiodevices
set -g @powerkit_plugin_audiodevices_keybinding_input "C-M-i"
set -g @powerkit_plugin_audiodevices_keybinding_output "C-M-o"

Set key to empty to disable:

# Disable theme selector keybinding
set -g @powerkit_theme_selector_key ""

# Disable plugin keybinding
set -g @powerkit_plugin_bitwarden_keybinding_password ""

Add your own keybindings to trigger helpers:

# In tmux.conf
bind-key C-x run-shell "~/.tmux/plugins/tmux-powerkit/src/helpers/my_helper.sh"

1. Check for conflicts: prefix + C-y
2. Verify key notation is correct
3. Ensure plugin is enabled
4. Check if action is set to skip

# Remove all PowerKit keybinding options
tmux show-options -g | grep powerkit.*key | cut -d' ' -f1 | xargs -I{} tmux set-option -gu {}

• Configuration - All options
• Helpers - Available helpers
• Helper Contract - Helper system