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

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, the comment_vim field is defined within the AppConfig struct at lines 124-130:

# ~/.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 (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 (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 lines 579-586 evaluates app.comment_vim_enabled:

// 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 (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	124-130	Defines comment_vim in configuration schema
src/main.rs	200-208, 579-586	Loads setting and routes comment-mode keystrokes
src/comment_vim.rs	18-55	Implements modal editor via edtui
src/ui/comment_panel.rs	52-71	Renders Vim hints and mode badge
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, 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.

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.

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