config.example.toml

# mackbind configuration example
#
# **All fields are optional.** You still get the full set of macOS keyboard
# habits without this file — every mapping is built into the defaults. This file
# is only for **adjusting** them.
#
# User config paths (lowest to highest priority):
#   /etc/mackbind/config.toml
#   ~/.config/mackbind/config.toml
#   $MACKBIND_CONFIG (highest priority; can be an extra file)
#
# ─────────────────────────────────────────────────────────────
# Modifier key swap
# ─────────────────────────────────────────────────────────────
# Default: CapsLock ↔ Left Ctrl are swapped as a pair.
# Set this to false to leave both keys untouched.
#
# swap_capslock_ctrl = true
#
# `remap` adds or overrides individual directions. A user entry with the same
# `from` key wins over the default pair.
#
# [[remap]]
# from = "KEY_CAPSLOCK"
# to   = "KEY_ESCAPE"
# desc = "CapsLock → Esc"
#
# To turn only CapsLock into Left Ctrl and leave Left Ctrl alone, disable the
# paired swap first, then add the one direction:
#
# swap_capslock_ctrl = false
# remap = [{ from = "KEY_CAPSLOCK", to = "KEY_LEFTCTRL" }]

# ─────────────────────────────────────────────────────────────
# Mapping rule table
# ─────────────────────────────────────────────────────────────
# **The single source of truth for mappings.** Each row answers "what the user
# pressed, what should be emitted".
#
# Three columns:
#   apps   the apps it applies to. Omit or ["*"] = all apps.
#          "TerminalEmulator" = determined from the .desktop Categories,
#          so newly installed terminals take effect automatically. Everything
#          else matches a wm_class substring.
#   keys   the combo the user actually presses, **not including Cmd** (Cmd is
#          implicit: pressing Meta alone emits nothing; only the combo decides
#          the output).
#          Key names use evdev form (KEY_A, KEY_LEFTBRACE); a prefix adds an
#          extra modifier: "S-z" = Shift+Z, "A-Left" = Alt+←.
#          "*" means the main-key wildcard (used with terminal_ctrl_shift).
#   action what to do. Two kinds:
#          emit               emit a fixed combo
#          de_accel           read the desktop environment's existing binding and emit the same keys
#          terminal_ctrl_shift  add Shift only if the app itself binds that key with Ctrl+Shift
#
# **Order is priority**: the first match from top to bottom wins. Your entries
# are **prepended before** the defaults, so a row with the same (app, keys)
# overrides the built-in row instead of being shadowed by it.
#
# To see the full effective table: `mackbind --verbose` (printed at startup)
#
# mods syntax: C=Ctrl, A=Alt, S=Shift, M=Cmd; combine with -, e.g. "C-S".
#
# [[rules]]
# keys   = ["KEY_HOME"]              # Cmd+Home
# action = { emit = { mods = ["A"], key = "KEY_HOME" } }
# desc   = "Jump to the start of the document"
#
# # In VSCode only, change Cmd+B to something else (it is already Ctrl+B globally by default)
# [[rules]]
# apps   = ["code"]
# keys   = ["KEY_B"]
# action = { emit = { mods = ["C"], key = "KEY_B" } }
#
# # In one app, change Cmd+Space to a different action
# [[rules]]
# apps   = ["firefox"]
# keys   = ["KEY_SPACE"]
# action = { de_accel = "overview" }

# ─────────────────────────────────────────────────────────────
# Fn key priority
# ─────────────────────────────────────────────────────────────
# fkeysfirst: pressing Fn gives brightness/media keys (default, same as kernel fnmode=2)
# fkeyslast: pressing Fn gives F1-F12 (same as kernel fnmode=1)
# disabled: no conversion
#
# fn_mode = "fkeysfirst"

# ─────────────────────────────────────────────────────────────
# Terminal behavior
# ─────────────────────────────────────────────────────────────
# VTE terminals cannot report Shift+Enter separately from Enter. By default
# mackbind emits Ctrl+J (0x0A) there, which inserts a newline in readline, vim,
# and agent TUIs. The terminal list is built in; you only choose on or off.
#
# [terminal]
# shift_enter = "on"    # default: emit Ctrl+J in VTE terminals
# shift_enter = "off"   # keep the terminal's native Shift+Enter

# ─────────────────────────────────────────────────────────────
# Desktop environment
# ─────────────────────────────────────────────────────────────
# DE-specific behavior is looked up here. The GNOME family is the most complete
# so far; under KDE / a bare WM, unsupported rules are **skipped** rather than
# erroring.
#
# gnome = GNOME / Mutter family (including ptyxis, GNOME apps)
# kde   = KDE Plasma
# none  = Sway, Hyprland, i3, etc., or any other environment without a lookup table
#
# DE-specific behavior is looked up here. The GNOME family is the most complete
# so far; under KDE / a bare WM, unsupported rules are **skipped** rather than
# erroring.
#
# [desktop]
# type = "gnome"

# Whether `Cmd+Space` (macOS Spotlight) is mapped to the desktop environment's
# overview.
#
# It works by **reading** the DE's existing binding and emitting the same keys,
# rather than rewriting the binding — so it leaves no record in your config and
# does not affect your own binding for that key.
#
# GNOME's overview action is `toggle-overview` (on this machine by default
# `Ctrl+Shift+Space`), which on macOS is "switch input method" — the semantics
# match as well.
# If no matching action is found it is skipped automatically, not treated as an
# error.
#
# Note: the `Cmd+Space` → overview rule is itself already built into the rule
# table (`de_accel { feature = "overview" }`); this is just the on/off switch.
#
# spotlight = true

# ─────────────────────────────────────────────────────────────
# Apps where Ctrl is already taken
# ─────────────────────────────────────────────────────────────
# Inside these apps Ctrl has an established meaning (Ctrl+C interrupts, Ctrl+V
# does block selection), so Cmd there must be mapped to **Ctrl+Shift** to avoid
# it. Used together with the `terminal_ctrl_shift` action in the rule table.
#
# **Terminals need not be listed** — determined by the freedesktop desktop entry
# spec: a `.desktop` whose `Categories` contains `TerminalEmulator` counts as a
# terminal, so newly installed terminals take effect automatically.
#
# This is only for exceptions outside terminals, for example a standalone gvim
# window.
#
# ctrl_busy_apps = ["gvim", "org.gnome.gedit"]

# ─────────────────────────────────────────────────────────────
# Requires an extension that provides focused-window info, used to distinguish by app
# ─────────────────────────────────────────────────────────────
# https://extensions.gnome.org/extension/focused-window-dbus/
#
# To verify it works (note that --dest must be org.gnome.Shell):
#   gdbus call --session --dest org.gnome.Shell \
#     --object-path /org/gnome/shell/extensions/FocusedWindow \
#     --method org.gnome.shell.extensions.FocusedWindow.Get