# How to Customize Vim Keybindings and Leader Key Shortcuts in tuicr

> Customize tuicr's Vim keybindings and leader key shortcuts by editing your config file or using runtime commands. Streamline your workflow today.

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

---

**You can customize tuicr's vim-style leader key and comment editing behavior by editing `~/.config/tuicr/config.toml` or using runtime commands like `:set leader ,` and `:vim`.**

tuicr is a terminal-based code review tool that adopts a vim-inspired interaction model for navigating diffs and managing comments. While it ships with sensible defaults—including a semicolon leader key and standard insert-mode commenting—you can extensively customize vim keybindings and leader key shortcuts in tuicr through its TOML configuration and interactive command prompt.

## Customizing the Leader Key in tuicr

The **leader key** acts as a prefix for shortcuts like toggling the file list (`<leader>e`) or opening the commit selector (`<leader>s`). By default, this is set to `;` (semicolon).

### Static Configuration via config.toml

Edit `~/.config/tuicr/config.toml` to set a persistent leader key:

```toml

# Use comma as the leader key instead of the default semicolon

leader = ","

```

The parser in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) expects a single-character string; longer values trigger a warning and are ignored (see line 131).

### Runtime Configuration with :set leader

Change the leader immediately without restarting:

```text
:set leader =

```

After execution, shortcuts like `=e` replace `;e`. The command handler maps this to the `leader` configuration key and updates `App.leader_key` on-the-fly in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs).

### Leader Key Routing Implementation

When you press the leader key, [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) handles the routing. The `map_normal_mode` function checks `if key == leader_key` and sets a pending-leader flag (lines 171–173), allowing the next keystroke to trigger the appropriate shortcut.

## Enabling and Using Vim-Style Comment Editing

By default, tuicr uses standard insert-mode text entry for comments. You can enable full modal editing (normal/insert modes with vim commands) for a more authentic experience.

### Activating Modal Comment Editing

Add this to your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml):

```toml
comment_vim = true

```

The boolean is read in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) (line 125) and stored in `App.comment_vim_enabled`. Toggle dynamically with `:vim` (enable) or `:novim` (disable) defined in [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/src/handler.rs).

### Navigating Comment Vim Modes

When commenting with vim mode enabled:

- **Insert mode**: Default when starting a comment (triggered by `i` or `A`)
- **Normal mode**: Press `Esc` or `:` to enter command mode

The state machine lives in [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs), where `handle_comment_vim_key`, `comment_vim_enter_normal`, and `run_comment_vim_command` manage transitions.

### Comment Vim Commands Reference

While in normal mode:

| Command | Action | Implementation |
|---------|--------|----------------|
| `:w` | Save comment | Maps to `CommentVimPending::Save` |
| `:q` | Cancel editing | Maps to `CommentVimPending::Cancel` |
| `A` | Edit at end of line | Switches to insert mode |

These are handled by `handle_comment_vim_key` in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (line 586) and forwarded to the comment-vim module. The UI reflects the current mode via `app.comment_vim_mode_label()` in diff view components ([`src/ui/diff_unified.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/diff_unified.rs), [`src/ui/diff_side_by_side.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/diff_side_by_side.rs)).

## Key Implementation Files

Understanding these source files helps when debugging or extending functionality:

- **[`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs)**: Parses `leader` and `comment_vim` from [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml)
- **[`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs)**: Maps leader key to pending actions and defines normal-mode shortcuts
- **[`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs)**: Applies config values to the `App` struct and routes leader-prefixed keys
- **[`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs)**: Implements the modal editing state machine for comments
- **[`src/ui/help_popup.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/help_popup.rs)**: Displays current leader key and comment-vim status (lines 138–152)

## Summary

- Customize the **leader key** statically in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) or dynamically via `:set leader <char>`
- Enable **vim-style comment editing** with `comment_vim = true` or the `:vim` command
- The default leader is `;`, but any single character works
- Modal comment editing supports `:w` to save and `:q` to cancel
- All routing logic resides in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) and [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs)

## Frequently Asked Questions

### What is the default leader key in tuicr?

The default leader key is `;` (semicolon). This prefixes all shortcuts, so `;e` toggles the file list and `;s` opens the commit selector according to the implementation in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs).

### Can I change the leader key without restarting tuicr?

Yes. Use the runtime command `:set leader <char>` (for example, `:set leader ,`). The change applies immediately to `App.leader_key` as implemented in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs), and all leader-prefixed shortcuts update automatically.

### How do I exit vim-style comment editing without saving?

Press `Esc` to enter normal mode, then type `:q` and press Enter. This triggers `CommentVimPending::Cancel` in [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs), discarding your changes and closing the comment editor.

### Where does tuicr store its configuration file?

tuicr reads configuration from `~/.config/tuicr/config.toml` on Linux/macOS. The [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) module parses this file at startup to load settings like `leader` and `comment_vim`.