# How to Customize the Leader Key and Shortcut Prefixes in tuicr

> Learn to easily customize the leader key and shortcut prefixes in tuicr. Modify your config.toml file to remap leader shortcuts and personalize your workflow. Get started today.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`:

```toml

# ~/.config/tuicr/config.toml

leader = ","

```

The value **must be a single character**. The parser in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) exposes `leader: Option<char>` and deserializes it from TOML.

2. **Application initialization** – In [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (lines 204‑205), the config value is assigned to the running application:

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

3. **UI rendering** – [`src/ui/help_popup.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs), applied in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) lines 204‑205, and rendered in [`src/ui/help_popup.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.