How the Superfile Hotkey System Works: Configuring Keybindings in yorukot/superfile

Superfile drives its keyboard shortcuts through a declarative TOML configuration file that maps action names to key combinations, registering them via the Tauri hotkey plugin with support for global, typing, and mode-specific scopes that reload dynamically without restarting the application.

Superfile is a modern terminal-based file manager built with Rust and Tauri. Its keyboard-driven workflow is governed by a flexible configuration system that allows users to remap actions, define multi-key shortcuts, and switch between default and Vim-style layouts by editing simple TOML files.

Architecture of the Hotkey System

The hotkey system in yorukot/superfile operates through a layered architecture that parses user configuration, merges it with built-in defaults, and registers listeners through the Tauri runtime.

TOML Configuration Parsing

When the application initializes, the core Rust layer reads src/superfile_config/hotkeys.toml using the toml crate. This file defines a mapping where each action name (such as list_down or copy_items) corresponds to an array of key strings. The parser validates these entries and constructs an internal map that links UI actions to their trigger keys.

Tauri Hotkey Plugin Integration

After parsing, each entry is registered with the Tauri hotkey plugin. This plugin creates native OS-level listeners that fire the associated action callback when the registered combination is pressed. The plugin supports modifier prefixes including ctrl+, shift+, alt+, and recognizes special keys like enter, esc, pgdown, and backspace.

Mode-Based Scoping

Hotkeys are organized into three distinct scopes that determine when they are active:

• Global hotkeys – Always active regardless of UI state. These handle navigation and core commands.
• Typing hotkeys – Take precedence when the user is focused on an input field. These override all other bindings to ensure text entry works correctly.
• Mode-specific hotkeys – Active only when the UI is in a specific mode (e.g., Normal vs. Selection). These allow context-sensitive commands.

Configuration File Structure

All keybinding customization centers on two files in the repository root.

Default Hotkeys Location

The primary configuration file is src/superfile_config/hotkeys.toml. This file contains the default mapping used when no user overrides are present. It is organized into sections:

• Global actions (lines 16-73)
• Typing overrides (lines 77-81)
• Mode-specific bindings (lines 84-96)

Action Definition Syntax

Each binding follows a strict pattern:

<action_name> = ['<key1>', '<key2>', ...]

For example, in src/superfile_config/hotkeys.toml:

list_down = ['down', 'j']
list_up = ['up', 'k']
copy_items = ['ctrl+c', '']
toggle_file_preview_panel = ['f', '']

• <action_name> must match a command recognized by the Superfile core.
• Keys use Tauri's syntax: lowercase key names with modifiers separated by plus signs.
• Empty strings ('') serve as placeholders when only one shortcut is needed.

Vim-Style Alternative Preset

For users preferring Vim conventions, the repository includes src/superfile_config/vimHotkeys.toml. This preset remaps navigation to h, j, k, l and adjusts other bindings to follow modal editing patterns. Users can replace the contents of hotkeys.toml with this file's contents to switch presets.

Practical Configuration Examples

The TOML-based system supports adding custom shortcuts, overriding specific modes, disabling unwanted bindings, and switching entire layouts.

Adding Custom Shortcuts

To bind Ctrl+Shift+S to the save_items action, append the following to hotkeys.toml:

save_items = ['ctrl+shift+s', '']

Save the file; Superfile's file watcher automatically registers the new shortcut without requiring a restart.

Overriding Mode-Specific Bindings

To remap the parent directory action to use h in Normal mode while preserving other modes, locate the Normal Mode section and modify:

# Normal Mode Actions

parent_directory = ['h', 'left', 'backspace']

This change affects only Normal mode, leaving Selection mode and global bindings untouched.

Disabling Unwanted Hotkeys

To completely disable a shortcut, provide an empty array:

quit = ['', '']

This removes all keybindings for the quit action, preventing accidental triggering.

Switching to Vim-Style Layouts

To adopt the Vim preset, copy the contents of src/superfile_config/vimHotkeys.toml into your active hotkeys.toml (or configure the application to load the Vim file directly). After saving, the interface immediately adopts h/j/k/l navigation and modal command structures.

Conflict Resolution and Precedence

When the same key appears in multiple scopes, Superfile resolves conflicts using a strict precedence order: typing → mode-specific → global.

If a user presses ctrl+c while typing in a search box, the typing scope wins even if ctrl+c is also mapped globally to copy_items. The configuration also warns about keys that conflict with core terminal controls (such as ctrl+c for interrupt signals) in the documentation at website/src/content/docs/configure/custom-hotkeys.mdx.

Dynamic Reloading Behavior

Superfile implements a file watcher on hotkeys.toml. When the file is modified and saved, the application re-parses the configuration, unregisters obsolete shortcuts from the Tauri plugin, and registers new bindings without terminating the process. This gives immediate feedback during configuration adjustments and eliminates the need to restart the file manager when refining keybindings.

Summary

• Superfile uses TOML configuration files (hotkeys.toml and vimHotkeys.toml) to define keybindings as mappings between action names and key arrays.
• The Tauri hotkey plugin registers these as native OS listeners supporting modifiers like ctrl+, shift+, and alt+.
• Three scopes control activation: global (always on), typing (input-focused), and mode-specific (context-dependent), with precedence following that order.
• Changes to src/superfile_config/hotkeys.toml are dynamically reloaded via file watching, applying immediately without restart.
• Users can disable shortcuts with empty arrays, add custom bindings with standard TOML syntax, or switch to Vim-style layouts by replacing the default file with vimHotkeys.toml.

Frequently Asked Questions

Where are the default keybindings defined in the Superfile source code?

The default keybindings are defined in src/superfile_config/hotkeys.toml within the repository. This file contains global shortcuts, typing overrides, and mode-specific actions. An alternative Vim-style preset is available at src/superfile_config/vimHotkeys.toml.

What is the syntax for defining a multi-key shortcut in Superfile?

Use a TOML array with Tauri-compatible key strings. For example, copy_items = ['ctrl+c', ''] assigns Ctrl+C to the copy action. Modifiers are written as prefixes (e.g., ctrl+shift+s), and empty strings act as placeholders when only one key is needed.

How does Superfile handle keybinding conflicts between different modes?

Superfile resolves conflicts using a precedence hierarchy: typing hotkeys override mode-specific hotkeys, which override global hotkeys. If a key is bound in both the global scope and the typing scope, the typing scope wins when the user is focused on an input field.

Can I change hotkeys without restarting Superfile?

Yes. Superfile watches the hotkeys.toml file for changes and automatically reloads the configuration when you save edits. The Tauri plugin unregisters old bindings and registers new ones immediately, allowing you to test configuration changes in real-time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}