# How to Enable Vim Modal Editing in Comment Boxes Using comment_vim Config in tuicr

> Enable Vim modal editing in tuicr comment boxes easily. Set comment_vim true in config or use the :vim command for seamless editing.

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

---

**Set `comment_vim = true` in your tuicr configuration file (typically `~/.config/tuicr/config.toml`) to enable Vim-style modal editing in comment boxes, or toggle it at runtime with the `:vim` command.**

The **comment_vim** configuration option transforms tuicr's comment editor from a standard line editor into a full modal Vim interface. This feature appeals to power users who prefer Vim's modal paradigm for text editing. When enabled, comment boxes display mode indicators (`INSERT`/`NORMAL`/`VISUAL`) and accept standard Vim keystrokes through the integrated **CommentVimEditor**.

## How the comment_vim Configuration Works

The `comment_vim` setting flows through several layers of tuicr's architecture to activate modal editing.

### Configuration Definition and Loading

In [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs), the `comment_vim` field is defined within the `AppConfig` struct at lines 124-130:

```toml

# ~/.config/tuicr/config.toml

comment_vim = true          # Enable Vim modal editing for comments

comment_tab_width = 4       # Spaces per Tab in Vim mode

```

During application startup, `App::new()` in [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (lines 200-208) calls `load_config()` and stores the parsed value in `App::comment_vim_enabled`. This boolean flag persists for the session unless modified by runtime commands.

### UI Rendering with comment_vim Enabled

The comment panel in [`src/ui/comment_panel.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs) (lines 52-71) checks `app.comment_vim_enabled` to conditionally render:

- A Vim-specific hint line replacing standard Emacs/Readline hints
- A `[MODE]` badge displaying the current modal state (`INSERT`, `NORMAL`, or `VISUAL`)

### Event Routing to the Modal Editor

While in comment mode, the main event loop at [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) lines 579-586 evaluates `app.comment_vim_enabled`:

```rust
// Pseudocode representing the routing logic
if app.comment_vim_enabled {
    handle_comment_vim_key(&mut self, &self.config, key);
} else {
    // Standard line editing path
}

```

The `handle_comment_vim_key` function delegates to the `CommentVimEditor` implementation.

## The CommentVimEditor Implementation

The core modal logic lives in **src/comment_vim.rs** (lines 18-55). This module wraps the `edtui` crate to provide:

| Component | Purpose |
|-----------|---------|
| Editor instance | Created in **Insert** mode by default |
| UTF-8 byte offset tracking | Maintains cursor position across edits |
| `feed_key()` | Translates keystrokes to buffer operations |
| `feed_paste()` | Handles multi-character input |

The editor supports three modes with standard Vim transitions:

- **Insert mode**: Direct text entry; press `Esc` to exit
- **Normal mode**: Command motions (`x`, `dd`, `p`, `hjkl` navigation)
- **Visual mode**: Selection operations

## Runtime Control: Toggling comment_vim Without Restarting

tuicr provides three commands to change the Vim editing state dynamically, defined in [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/src/handler.rs) (lines 54-56):

| Command | Equivalent | Effect |
|---------|------------|--------|
| `:vim` | `set vim` | Enables Vim modal editing immediately |
| `:novim` | `set novim` | Disables Vim modal editing, returns to line editor |

These update `app.comment_vim_enabled` in place, requiring no configuration file changes or application restart.

## Practical Usage Workflow

1. **Open a comment box** — Press `a` to add a new comment or `e` to edit existing
2. **Observe the mode indicator** — Header shows `[INSERT]` or `[NORMAL]`
3. **Edit in Insert mode** — Type normally; press `Esc` to switch modes
4. **Execute Normal mode commands** — `x` (delete char), `dd` (delete line), `0`/`$` (line bounds)
5. **Access command line** — Press `:` for `:w` (save) or `:q` (discard)
6. **Confirm and exit** — `Alt-Enter` or `Shift-Enter` submits the comment

## Key Source Files for comment_vim

| File | Lines | Responsibility |
|------|-------|----------------|
| [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) | 124-130 | Defines `comment_vim` in configuration schema |
| [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) | 200-208, 579-586 | Loads setting and routes comment-mode keystrokes |
| [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs) | 18-55 | Implements modal editor via `edtui` |
| [`src/ui/comment_panel.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/comment_panel.rs) | 52-71 | Renders Vim hints and mode badge |
| [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/src/handler.rs) | 54-56 | Declares runtime toggle commands |

## Summary

- Set `comment_vim = true` in `~/.config/tuicr/config.toml` to enable permanent Vim editing
- Use `:vim` or `set vim` to activate without restarting; `:novim` to disable
- The feature routes through `CommentVimEditor` in [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs), built on `edtui`
- Mode indicators (`INSERT`/`NORMAL`/`VISUAL`) appear in the comment box header
- Standard Vim motions and commands work; `Alt-Enter` submits the final text

## Frequently Asked Questions

### What Vim features are supported in tuicr's comment_vim mode?

The implementation covers core modal editing: mode switching, motion commands, deletion/yanking, paste operations, and command-line mode for save/quit. Advanced features like macros, registers beyond the default, and custom key mappings are not present. The underlying `edtui` crate provides the foundation, so capabilities expand as that dependency evolves.

### Why doesn't my comment_vim setting take effect immediately?

Configuration changes require an application restart because `App::comment_vim_enabled` is set once during `App::new()` initialization. For on-the-fly changes, use the `:vim` or `:novim` commands instead, which modify the runtime flag directly without reloading the configuration file.

### Can I use comment_vim with custom Tab widths?

Yes. The `comment_tab_width` setting (default 4) controls spaces inserted by the Tab key specifically in Vim mode. This operates independently of the modal configuration but only applies when `comment_vim = true`. The value is passed to the `CommentVimEditor` initialization in [`src/comment_vim.rs`](https://github.com/agavra/tuicr/blob/main/src/comment_vim.rs).

### How does comment_vim handle multibyte UTF-8 characters?

The `CommentVimEditor` tracks cursor position as a **UTF-8 byte offset** rather than character count. This ensures accurate positioning and slicing for characters outside ASCII range. When rendering, the UI converts byte offsets to display positions for the terminal interface.