# How to Configure the Leader Key for Leader-Based Shortcuts in tuicr > Easily configure the leader key in tuicr to create custom leader-based shortcuts. Personalize your workflow by setting your preferred leader character in config.toml. - Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr) - Tags: how-to-guide - Published: 2026-08-07 --- **Set the `leader` field in your [`config.toml`](https://github.com/agavra/tuicr/blob/main/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 (`e`) or focusing the diff view (`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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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 (`,`)** ```toml # ~/.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** ```toml # 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`](https://github.com/agavra/tuicr/blob/main/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. ```rust // Conceptual representation based on src/config/mod.rs fn read_leader(table: &toml::Table) -> Option { 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` in the configuration struct (`cfg.leader`). During application startup in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs), this value is applied to the running instance: ```rust // 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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/app/init.rs) as `DEFAULT_LEADER_KEY`. - **Configuration**: Set `leader = "x"` (where `x` is any single character) in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) to customize the prefix. - **Validation**: The parser in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/main.rs) and immediately affects all leader-based shortcuts in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs). - **UI Consistency**: The help system in [`src/ui/help_popup.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) always reserves the configured leader character for prefix matching.