How to Configure the Leader Key for Leader-Based Shortcuts in tuicr

Set the leader field in your config.toml to any single printable character (for example, leader = ",") to replace the default semicolon (;) prefix used for all leader-based commands.

The leader key in tuicr acts as a modal prefix for quick-access shortcuts such as toggling the file tree (<leader>e) or focusing the diff view (<leader>f). By modifying the user configuration file, you can remap this prefix to any single character that does not conflict with your workflow. The configuration is validated at startup and dynamically reflected in the application's help system.

Understanding the Leader Key Default Behavior

By default, tuicr uses the semicolon (;) as the leader key. This value is defined as DEFAULT_LEADER_KEY in src/app/init.rs and is hardcoded to ';' unless overridden by user configuration.

When the application starts, it initializes an App struct with this default value. The leader key then acts as a prefix in normal mode: pressing the leader key followed by a command key triggers specific actions defined in the keybinding map. For example, the sequence ;e toggles the file explorer, while ;s opens the commit selector.

Configuration File Structure

tuicr reads user settings from a config.toml file located in the standard configuration directory (typically ~/.config/tuicr/config.toml on Linux/macOS or the equivalent OS-specific path).

The parser expects the leader entry to be a single-character string at the top level of the configuration or within the [core] table. If the value is missing, empty, longer than one character, or of a non-string type, the parser emits a warning and falls back to the default semicolon.

Setting the Leader Key in config.toml

To customize the leader key, add the leader field to your configuration file and assign it a single character value.

Example: Changing the leader key to comma (,)

# ~/.config/tuicr/config.toml

leader = ","

After restarting tuicr, all leader-based shortcuts now use the comma prefix. For instance, ,e toggles the file list and ,f focuses the diff view.

Example: Invalid configuration handling

# This value is ignored because it exceeds one character

leader = "space"

When tuicr encounters this configuration, it logs a warning and reverts to the default ; key.

Parsing and Validation Logic

The configuration parsing is implemented in src/config/mod.rs within the read_leader function. This function extracts the leader field from the TOML table and validates that it is exactly one character long.

// Conceptual representation based on src/config/mod.rs
fn read_leader(table: &toml::Table) -> Option<char> {
    if let Some(val) = table.get("leader") {
        if let Some(s) = val.as_str() {
            if s.chars().count() == 1 {
                return s.chars().next();
            }
        }
        eprintln!("Warning: 'leader' must be a single character");
    }
    None
}

The validated value is stored as Option<char> in the configuration struct (cfg.leader). During application startup in src/main.rs, this value is applied to the running instance:

// From src/main.rs
if let Some(leader) = cfg.leader {
    app.leader_key = leader;
}

Integration with Keybindings and UI

Once configured, the leader key integrates deeply into the input handling system defined in src/input/keybindings.rs. The map_normal_mode and map_file_tree_mode functions check for the leader key before processing other normal-mode commands, ensuring that leader-prefixed shortcuts take precedence over overlapping filter bindings (such as the e or i filters in the file tree).

The dynamic nature of the leader key is also reflected in the user interface. The help popup implemented in src/ui/help_popup.rs reads the current app.leader_key value and injects it into the shortcut listings. This ensures that the interactive help screen always displays the correct key combination (e.g., displaying ,e instead of ;e when comma is configured).

Summary

• Default Value: tuicr uses ; as the default leader key, defined in src/app/init.rs as DEFAULT_LEADER_KEY.
• Configuration: Set leader = "x" (where x is any single character) in config.toml to customize the prefix.
• Validation: The parser in src/config/mod.rs enforces single-character strings and falls back to the default if validation fails.
• Application: The value is applied at runtime in src/main.rs and immediately affects all leader-based shortcuts in src/input/keybindings.rs.
• UI Consistency: The help system in src/ui/help_popup.rs dynamically reflects the configured leader key.

Frequently Asked Questions

What is the default leader key in tuicr?

The default leader key is the semicolon (;). This value is hardcoded in src/app/init.rs as the constant DEFAULT_LEADER_KEY and is used when no valid configuration is provided or when the configuration file is missing.

Can I use a multi-character string as the leader key?

No, tuicr strictly requires the leader key to be a single character. The validation logic in src/config/mod.rs checks the string length; if it contains zero or multiple characters, the application emits a warning and reverts to the default semicolon (;).

Where does tuicr store the leader key configuration?

The leader key is configured in the config.toml file, typically located at ~/.config/tuicr/config.toml on Unix-like systems. The leader field should be placed at the top level of the TOML file or within the [core] section, depending on your configuration structure.

How do I disable the leader key entirely?

You cannot completely disable the leader key, but you can leave the configuration unset or set it to an invalid value to force the use of the default semicolon. To effectively neutralize leader shortcuts, you would need to avoid pressing the leader key, as the input system in src/input/keybindings.rs always reserves the configured leader character for prefix matching.

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