How to Customize Vim Keybindings and Leader Key Shortcuts in tuicr

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:

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

leader = ","

The parser in 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:

: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.

Leader Key Routing Implementation

When you press the leader key, 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:

comment_vim = true

The boolean is read in 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.

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, 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 (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, src/ui/diff_side_by_side.rs).

Key Implementation Files

Understanding these source files helps when debugging or extending functionality:

• src/config/mod.rs: Parses leader and comment_vim from config.toml
• src/input/keybindings.rs: Maps leader key to pending actions and defines normal-mode shortcuts
• src/main.rs: Applies config values to the App struct and routes leader-prefixed keys
• src/comment_vim.rs: Implements the modal editing state machine for comments
• 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 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 and 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.

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, 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, 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 module parses this file at startup to load settings like leader and comment_vim.

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