How to Customize the Leader Key and Shortcut Prefixes in tuicr

Set leader = "," (or any single character) in ~/.config/tuicr/config.toml and restart tuicr to remap all <leader> shortcuts.

The leader key in tuicr is a configurable prefix that triggers Vim‑style shortcuts for common actions. By default, it is set to ;, which means shortcuts like <leader>e or <leader>s are entered as ;e or ;s. According to the agavra/tuicr source code, you can change this leader key to any single character through your configuration file.

Setting the Leader Key in config.toml

The leader key is defined by the leader field in your tuicr configuration. To customize it, edit ~/.config/tuicr/config.toml:

# ~/.config/tuicr/config.toml

leader = ","

The value must be a single character. The parser in src/config/mod.rs (lines 31‑33) validates this field as Option<char>, and invalid values are ignored.

After saving the file, restart tuicr to apply the change. There is no CLI flag or runtime command to modify the leader key without a restart.

How the New Leader Affects Shortcuts

Once configured, every shortcut written as <leader>… automatically uses your chosen character. The keybinding logic in src/input/keybindings.rs resolves these mappings during the map_normal_mode function.

Common leader‑prefixed actions include:

• <leader>e – toggle the file‑list panel
• <leader>s – show or hide the commit selector pane (equivalent to :set commits!)
• <leader>f – toggle single‑file focus (equivalent to :focus)
• <leader>c – open the comment input box

With leader = ",", you would press ,e, ,s, ,f, and ,c respectively.

Internal Implementation

The leader key flows through three main components of the codebase:

1. Configuration parsing – src/config/mod.rs exposes leader: Option<char> and deserializes it from TOML.

2. Application initialization – In src/main.rs (lines 204‑205), the config value is assigned to the running application:

   // src/main.rs
   if let Some(leader) = cfg.leader {
       app.leader_key = leader;   // line 204‑205
   }

3. UI rendering – src/ui/help_popup.rs (lines 138‑166) displays the current leader key in help text so users always see their active binding.

The map_key_to_action function in src/input/keybindings.rs receives the leader key and uses it to match pending‑leader state transitions.

Limitations and Caveats

• Single character only – Multi‑character strings or special key names are rejected by the parser.
• No runtime changes – Editing the config requires a full restart; there is no :set leader= command.
• Case sensitivity – The leader is matched exactly as configured; , and ; are distinct from their shifted variants.

Summary

• Add leader = "x" to ~/.config/tuicr/config.toml where x is your preferred single character.
• Restart tuicr to activate the new leader key.
• All <leader> shortcuts automatically adapt to the new prefix.
• The configuration is validated in src/config/mod.rs, applied in src/main.rs lines 204‑205, and rendered in src/ui/help_popup.rs.

Frequently Asked Questions

Can I set the leader key to a special key like Space or Tab?

No. The leader field in src/config/mod.rs is parsed as Option<char>, which accepts only single printable characters. Special keys like Space, Tab, or Enter cannot be used as the leader key.

Does changing the leader require rebuilding tuicr from source?

No. The leader key is read from your external config.toml at startup. You only need to edit the configuration file and restart the binary; no recompilation is necessary.

Will my custom leader appear in the built‑in help popup?

Yes. The help popup in src/ui/help_popup.rs dynamically inserts your configured leader key into the shortcut descriptions, so the displayed shortcuts always match your active configuration.

Is there a way to have different leader keys for different modes?

No. tuicr implements a single global leader key stored in app.leader_key. The map_key_to_action system does not support mode‑specific leaders in the current codebase.

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