# How to Use Vim Keybindings in Tuicr: A Complete Guide to Keyboard Navigation

> Master Vim keybindings in Tuicr for efficient terminal navigation. This guide covers modal editing across Normal, Command, Search, and Comment modes. Configure your leader key now.

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

---

**Tuicr implements Vim-style navigation by mapping terminal key events to internal `Action` enums through the `map_key_to_action` function in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs), supporting modal editing across Normal, Command, Search, and Comment modes with a configurable leader key.**

Tuicr is a terminal UI code review tool that brings the efficiency of Vim to GitHub pull request navigation. The application implements a comprehensive modal keybinding system that translates familiar Vim shortcuts into code review actions. Understanding how Tuicr handles vim keybindings allows you to navigate diffs, comments, and commits without leaving the home row.

## Understanding the Keybinding Architecture

The keybinding system in Tuicr is isolated in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) and driven by the central dispatcher in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs). This architecture separates input handling from application logic, making the system highly extensible.

### The Central Mapper Function

All keyboard input flows through `map_key_to_action`, which translates `KeyEvent` structs into `Action` enums based on the current **InputMode**. According to the agavra/tuicr source code, the function signature evaluates the key code, modifiers, and active mode before returning the appropriate action. These actions then update the application state (`App`) defined in [`src/app.rs`](https://github.com/agavra/tuicr/blob/main/src/app.rs).

```rust
// Example: moving the cursor down one line (Vim "j") in Normal mode
let key = KeyEvent::new(KeyCode::Char('j'), KeyModifiers::NONE);
let action = map_key_to_action(key, InputMode::Normal, ';');
assert_eq!(action, Action::CursorDown(1));

```

## Navigating Normal Mode Like Vim

**Normal mode** serves as the default navigation layer in Tuicr, activated when no dialog or input field is focused. The `map_normal_mode` function contains match arms that interpret keys according to Vim conventions.

### Basic Movement Keys

Standard Vim navigation works exactly as expected. The `j` and `k` keys move the cursor vertically, while `h` and `l` handle horizontal scrolling. In [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) lines 64-66, the line-down mapping translates the `j` key or Down arrow directly to `Action::CursorDown(1)`.

### Paging and File Navigation

For rapid navigation through large diffs, Tuicr supports Vim's paging commands:

- **Ctrl-d/u** – Scroll half-page down or up
- **Ctrl-f/b** – Scroll full-page forward or backward
- **g/G** – Jump to the top or bottom of the current view
- **}** and **{** – Navigate between hunks or sections
- **]** and **[** – Move between files in the pull request
- **m/M** – Traverse between comments

## Using the Leader Key System

Tuicr implements a **leader key** mechanism (default `;`) that enables custom shortcuts through "pending" actions. When you press the leader key in Normal mode, the system waits for a second keypress to complete the command.

The leader handling appears as the first match in `map_normal_mode` at lines 60-62 of [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs). This design allows you to chain commands without conflicting with built-in Vim motions. For example, pressing `;` followed by another key can trigger specialized code review actions while preserving standard `;` functionality in other contexts.

## Editing Comments with Vim Shortcuts

When entering **Comment mode** to write pull request feedback, Tuicr maintains Vim-style editing keys through the `map_comment_mode` function (lines 89-100). These bindings provide efficient text manipulation without lifting your fingers from the keyboard:

- **Ctrl-a/e** – Jump to the start or end of the current line
- **Alt-←/→** – Navigate by word boundaries
- **Ctrl-w** – Delete the previous word
- **Esc** – Cancel the comment and exit to Normal mode

```rust
// Example: exiting comment input with Escape (Vim "Esc") in Comment mode
let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
let action = map_key_to_action(key, InputMode::Comment, ';');
assert_eq!(action, Action::ExitMode);

```

## Working Across Other Modal States

Tuicr extends Vim keybindings beyond Normal and Comment modes. The **Command mode** (`:`), **Search mode** (`/`), **Help mode** (`?`), and commit selection dialogs all reuse familiar Vim motions.

Each mode has a dedicated mapper function—`map_command_mode`, `map_help_mode`, and others—that follows the same pattern of key-to-action translation. For instance, `j` and `k` navigate lists vertically in commit selection dialogs, while `h` and `l` scroll horizontally through long lines.

```rust
// Example: toggling a line comment with Vim "c" in Normal mode
let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::NONE);
let action = map_key_to_action(key, InputMode::Normal, ';');
assert_eq!(action, Action::AddLineComment);

```

## Summary

- **Tuicr uses `map_key_to_action`** in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs) to translate terminal input into application commands across all UI modes.
- **Normal mode supports standard Vim motions** including `hjkl` navigation, Ctrl-d/u paging, and bracket-based file traversal.
- **The leader key (`;` by default)** enables custom two-key shortcuts without breaking standard Vim conventions.
- **Comment mode preserves Vim editing shortcuts** like Ctrl-a/e for line navigation and Ctrl-w for word deletion.
- **All modes share consistent navigation patterns**, making the transition between reviewing code, writing comments, and executing commands seamless.

## Frequently Asked Questions

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

The default leader key is the semicolon (`;`). You can trigger pending actions by pressing this key followed by a second key in Normal mode. The leader handling is defined at the beginning of the `map_normal_mode` function in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs).

### How do I navigate between files in a pull request using Vim keys?

Use the `]` and `[` keys to jump to the next or previous file in the pull request. These mappings are part of the Normal mode keybindings in `map_normal_mode`, translating directly to file navigation actions.

### Can I customize the Vim keybindings in Tuicr?

Yes, because the mapping layer is isolated in [`src/input/keybindings.rs`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs), you can modify or extend shortcuts by editing the corresponding mapper functions. Each mode has its own sub-mapper (e.g., `map_normal_mode`, `map_comment_mode`) where key-to-action relationships are explicitly defined.

### How do I exit comment input mode and return to navigation?

Press the **Escape** key to cancel comment input and return to Normal mode. This sends `Action::ExitMode` through the dispatcher, as implemented in the `map_comment_mode` function at lines 89-100 of the keybindings file.