MouseVim

English · 简体中文（主要维护版本） · 繁體中文 · 日本語 · 한국어 · Deutsch · Français · Español · Português (Brasil) · Русский

A mouse-friendly Vim extension for native VS Code editing.

Vim for navigation and commands. VS Code for typing and selections.

MouseVim is an unofficial lightweight modification of VSCodeVim.

• Normal and Visual modes retain Vim behavior.
• INSERT mode uses the native VS Code editor.
• Selecting text with the mouse also switches to INSERT mode (the native VS Code editor), making mouse interaction more natural.
• You can switch between Hybrid and Full Vim. Full Vim behaves exactly like VSCodeVim, while Hybrid combines Vim with the native VS Code editor.
• If you also want some native Vim INSERT shortcuts while in INSERT mode, you can enable them through configuration. See Enabling Vim Insert features in Hybrid.

Note:

• MouseVim preserves VSCodeVim's vim.* settings. MouseVim and VSCodeVim cannot be installed at the same time.

Basic MouseVim usage

Insert in Hybrid

When you enter Hybrid Insert, MouseVim switches directly to the native VS Code editor. For example:

• Ctrl+A, Ctrl+X, Ctrl+C, and Ctrl+V perform Select All, Cut, Copy, and Paste.
• Backspace, Delete, Enter, Tab, and the arrow keys use native behavior.
• Native undo/redo, completion, snippets, automatic bracket closing, and format-on-type remain available.
• Ctrl+D, Alt+Click, and native multiple cursors remain available.
• Mouse clicks, dragging, double-clicking, triple-clicking, line-number selection, and scrolling use native behavior.

Comparing Hybrid and Full Vim

How Hybrid changes modes

Normal (Vim)
  ├─ i / a / c / o ... ──> Hybrid Insert (native VS Code)
  │                             └─ Escape ──> Normal (Vim)
  ├─ v / V / Ctrl+V ─────> Vim Visual
  └─ External non-empty selection/
     multiple cursors ────> Hybrid Insert (native VS Code)

Switching between Hybrid and Full Vim

• Click the VIM HYBRID or VIM FULL item in the status bar.
• Run the vim.cycleInteractionProfile command or bind it to a keyboard shortcut.
• Set the profile in settings.json.
  • This setting controls the profile used when VS Code starts. The default is hybrid.

{
  "vim.interactionProfile": "hybrid"
}

How selection ownership is determined

Hybrid determines ownership from the source of a selection.

Managed by Vim:

• Character, line, and block selections created with v, V, and Ctrl+V.
• Changes produced by Vim motions while already in Vim Visual.

Managed by the native VS Code editor:

• The mouse, Shift navigation, Ctrl+A, and Ctrl+D.
• Smart Select, snippet placeholders, completion, refactoring, search, and selections created by other extensions.
• Multiple empty cursors and multiple non-empty selections.

Enabling Vim Insert features in Hybrid

Configuration can retain selected Vim features and shortcuts while in Insert.

Note: not every feature is guaranteed to work correctly.

How to enable them

The relevant settings.json setting is:

{
  "vim.hybridInsertVimFeatures": []
}

Enable individual features as needed.

For example, with the following configuration, Ctrl+U in INSERT deletes to the start of the line, matching Vim behavior:

{
  "vim.interactionProfile": "hybrid",
  "vim.hybridInsertVimFeatures": ["insertModeMappings", "ctrlBracket", "ctrlO", "ctrlU"]
}

Recommended Hybrid Insert options

The following commonly used Vim INSERT shortcuts are recommended.

Note: they are disabled by default to preserve the principle that INSERT uses the native VS Code editor. However, these features are very common for Vim users, so you may want to enable them:

{
  "vim.interactionProfile": "hybrid",
  "vim.hybridInsertVimFeatures": [
    "ctrlBracket",
    "ctrlO",
    "ctrlR",
    "ctrlW",
    "ctrlU",
    "ctrlN",
    "ctrlP"
  ]
}

Why these options:

• ctrlBracket: exits Insert; a classic shortcut with few conflicts.
• ctrlO: temporarily runs one Normal command, a very useful Vim capability.
• ctrlR: inserts register contents, for which native VS Code has no direct equivalent.
• ctrlW: deletes the previous word.
• ctrlU: deletes to the start of the line.
• ctrlN / ctrlP: selects the next or previous completion item, consistent with modern Neovim completion tools such as Blink and nvim-cmp. MouseVim directly invokes VS Code's selectNextSuggestion / selectPrevSuggestion, so the native completion list remains in use.

Supported configuration options

• Mappings and exits: insertModeMappings, ctrlBracket, ctrlAt.
• One Normal command: ctrlO, ctrlBackslashO.
• Registers and editing: ctrlR, ctrlW, ctrlU, ctrlH, ctrlT, ctrlD, ctrlE, ctrlY.
• Digraphs, newlines, and completion: ctrlK, ctrlJ, ctrlM, ctrlN, ctrlP, ctrlXCompletion.
• Other behavior: ctrlGUndoBreak, insertReplace, undoGrouping, macroRecording, dotRepeat.

These options are experimental and are not equivalent to complete Vim Insert semantics:

• ctrlXCompletion currently includes only the implemented Ctrl+X Ctrl+L line completion.
• ctrlR supports basic register forms and the implemented literal insertion prefixes, but does not promise to reproduce every Vim auto-indent difference.
• macroRecording and dotRepeat record only document changes that can be described deterministically.
• Completion, snippets, formatting, refactoring, multi-document edits, or external edits of unknown origin safely reject replay.
• If the same document changes in another pane while a native Insert session is suspended, the session preserves its edits and selections but is marked unsafe to replay.
• ctrlD overrides VS Code's native “Add Selection To Next Find Match,” ctrlY may override redo, and ctrlXCompletion uses the native cut prefix.
• The input method composition lifecycle always remains under VS Code's control.

Switch to fullVim when you need complete Vim Insert behavior.

Installation

Search for MouseVim in the VS Code Marketplace and verify this extension identifier:

laikang287.mousevim

Changes MouseVim makes to VSCodeVim

Internationalization

The following content is localized:

• Display name, description, command titles, keybinding titles, setting descriptions, and enum descriptions.
• Notifications, input prompts, Quick Pick descriptions, status bar descriptions, and similar UI text.

The following languages are supported:

Hybrid mode

• Adds Hybrid mode, which switches to the native VS Code editor while in INSERT.
• Adds related settings, commands, and other functionality. See the documentation for details.

Status bar

• Adds a text button to the status bar. Click it to switch quickly between VIM HYBRID and VIM FULL.
• Note: clicking the Vim mode item in the status bar enables or disables Vim. For example, clicking -- NORMAL -- disables Vim. This is an original VSCodeVim feature.

Automatically entering Insert with a non-English input method

In NORMAL or VISUAL, when the input method produces non-ASCII text or starts composition—for example, when a Chinese Pinyin input method combines several typed letters before committing text—MouseVim enters INSERT mode (the native VS Code editor) and commits the input.

This setting is disabled by default. Enable it when needed; it applies only to Hybrid:

{
  "vim.hybridAutoEnterInsertOnImeInput": true
}

The reasoning behind this setting is:

In pure Vim, if a user switches to a non-English input method and then types in NORMAL, Normal commands cannot be used as expected—for example, pressing yy may no longer copy the whole line. The user is probably in one of the following situations. This setting is intended for the first, not the second:

• The user wants to type text directly but forgot to enter INSERT.
• The user wants to use NORMAL features but forgot to switch to an English input method.

Known issues in Hybrid

Hybrid has the following known issues. If you encounter them, you may need to switch temporarily to fullVim:

• When Hybrid switches to INSERT, it switches to the native VS Code editor. This can be understood as temporarily leaving Vim. As a result, a macro cannot be recorded correctly if it includes a switch to INSERT. Dot repeat (.) has a similar limitation.
• Some features from the original Vim INSERT mode may not work.
  • Although Hybrid can enable selected Vim INSERT features and shortcuts through configuration while using the native VS Code editor, not every feature is guaranteed to work correctly. See Vim Insert features in Hybrid.

See the upstream documentation for normal VSCodeVim commands, settings, mappings, and plugins. Report MouseVim problems in this repository's Issues, and ask usage questions in Discussions.

Differences from VSCode Neovim

VSCode Neovim also provides a “Vim Normal/Visual + native VS Code Insert” experience. The main differences are the Vim backend and compatibility goals.

If you need a complete Neovim experience, Lua configuration, and the plugin ecosystem, VSCode Neovim is a better fit.

If you already use VSCodeVim and only want native Insert, multiple cursors, and more natural VS Code interaction, MouseVim is a better fit.

Attribution

MouseVim is forked from VSCodeVim/Vim and retains its mature Vim emulation, contribution history, and MIT license. MouseVim is not an official VSCodeVim distribution.

License

This project is licensed under the MIT License. See LICENSE, which preserves the upstream VSCodeVim copyright notice and the MouseVim fork notice.

Documentation and maintenance

• README

README.zh-CN.md is written manually. README.md (the English version) and READMEs in other languages are AI translations. For future updates, update README.zh-CN.md and README.md first.

• Documents under docs

These documents are AI-generated and are intended mainly as references. If needed, you can glance through each index to see what content is available.

• Project maintenance

MouseVim is only a lightweight modification of VSCodeVim and is not intended for continuous maintenance. Maintenance will be considered during the project's initial stage, when serious bugs exist, or when official VSCodeVim receives a major update.

• All code is written by AI

I am responsible for the product design direction, while the coding is handled by AI.

Why the name MouseVim?

The original name was VimCodeHybrid. Later, I found that VimCodeHybrid looked too similar to the VimCode project and might cause confusion, so I renamed it MouseVim. This is why the plugin's primary mode is called Hybrid rather than Mouse.

Personally, I think MouseVim is less descriptive of the project than VimCodeHybrid, but I also quite like the name MouseVim.