ViNEL

ViNEL Is Not an Emulation Layer — Vim / Neovim modal editing for VS Code. (An ode to Wine and Vi.)

What it is

Vim's modal editing — Normal / Visual / Insert modes, operators, text objects, dot-repeat, find-char, counts — built as a native state machine on top of VS Code, not a Vim emulation and not a Neovim bridge.

• Normal mode does what Vim would do; Insert mode does what VS Code would do (typing is 100% native — ViNEL never touches it). By design, Insert mode stays plain VS Code: Vim's insert-mode shortcuts (like Ctrl-R) are deliberately left out so Insert feels exactly like the editor you know.
• Every command routes straight to VS Code's own commands (cursor moves, edits, undo, find). No type-command hijacking, no shadow undo tree — the two things that make other Vim extensions lag on big files and mangle undo.
• A status-bar badge shows the mode: ☯ NORMAL · ☯ INSERT · ☯ VISUAL · ☯ V-LINE. The block/line cursor tracks it.

Everything below is count-aware — prefix a number (3dd, 5j, 2ci").

Controls

Modes & entering Insert

Motions (Normal & Visual)

Operators & edits (Normal)

Marks & registers

Macros

Macros are entirely ViNEL's own — no companion extension, ever. They record literal keystrokes: ViNEL commands, the characters you type in Insert, and the Insert-mode navigation keys you press (arrows, Backspace, Home/End). Replay re-issues typed characters through VS Code's real typing pipeline, so auto-indent, auto-closing pairs, auto-surround, and LSP edits all react on replay exactly as they did while recording — e.g. selecting a word and typing ' to wrap it replays as a wrap, not a literal quote. Replay honors a numeric prefix with no pop-up dialog — type the count, fire the chord, done.

(How, without the always-on type hijack that makes other Vim extensions lag: the keystroke capture — a scoped type override plus recording-only navigation keybindings — is installed only while the red badge is showing and torn down the instant you stop. Off the record path, Insert typing is 100% native.)

Cmd+F2 (Mac) / Ctrl+F2 (Windows/Linux) and F3 are state-independent: unlike q/@ (Normal-only), they fire in every mode — start recording mid-Insert, keep typing, stop without leaving home row. A red ⏺ REC badge sits in the status bar while recording. Cmd/Ctrl+F3 replays whatever you recorded most recently (a q{letter} macro or an F2 one) and restores the mode you recorded from, so playback is correct wherever you trigger it.

The one place ViNEL touches type is Replace mode, and only while R is active (the handler is disposed the instant you leave it) — Insert-mode typing is always 100% native.

F2/F3 are only the defaults — change the record/playback combos to whatever you like. See Customizing keybindings.

Blockwise Visual (Ctrl-V)

Blockwise selects the same columns across a range of lines — a tall box instead of a run of text. Its signature move is block insert: make a column selection down N lines, press I (or A), type once, Esc — and the text lands on every line at that column. ViNEL does this with VS Code's own multi-cursor (one cursor per row), so the broadcast typing is fully native.

Ctrl-V note: on Windows/Linux Ctrl-V is normally Paste; ViNEL rebinds it to blockwise Visual while in Normal/Visual (matching vim). Paste on Mac is Cmd+V and is unaffected. To keep Ctrl-V as paste, remove/rebind vinel.enterVisualBlock in your keybindings.json (same mechanism as above).

Ex-commands (:)

Opens VS Code's input box; Enter runs, Escape cancels.

Ranges: % (whole file), n,m, . (current), $ (last), '<,'> (Visual selection); no range = current line.

Substitution patterns are JavaScript RegExp (not full vim regex) — literals, \d, groups, \1 backrefs, & = whole match all work; \v/\zs/\< do not. One :%s is a single undo.

Text objects (after d/c/y, or in Visual)

Use a instead of i for the "around" (delimiters-included) form: ci", da(, yi{, vip, …

Surround (vim-surround)

{c} is one of )( b · ][ · }{ B · >< · " ' ` · t (tag). The "open" variants add inner spaces: ysiw( → ( word ), ysiw) → (word). Tip: ys must be followed straight away by a motion/object (as in vim).

Visual mode

Editor & IDE (VS Code's own power, under Vim keys)

These route straight to VS Code's built-in commands, so you get full IDE features with Vim muscle memory. All are ordinary keybindings you can change — see Customizing keybindings.

Customizing keybindings

Every key here is rebindable — nothing is locked. ViNEL contributes plain VS Code keybindings, so you override them the same way you'd override any built-in shortcut. The macro record and playback combos are the ones people most often want to change, so here's exactly how.

The two macro shortcuts (defaults)

Option A — the Keyboard Shortcuts UI (no JSON)

1. Open the Command Palette (Cmd/Ctrl+Shift+P) → Preferences: Open Keyboard Shortcuts.
2. In the search box type ViNEL: Toggle macro recording (or ViNEL: Replay last macro).
3. Double-click the row, press your desired key combo, hit Enter. Done — your binding automatically takes priority over the default.

Option B — edit keybindings.json directly

Command Palette → Preferences: Open Keyboard Shortcuts (JSON), then add:

[
  // Pick any combos you like — these replace F2 / F3:
  { "key": "cmd+shift+2", "command": "vinel.macroRecordToggle", "when": "editorTextFocus" },
  { "key": "cmd+shift+3", "command": "vinel.macroPlayLast",     "when": "editorTextFocus" },

  // OPTIONAL — turn OFF the built-in F2 / F3 defaults (prefix the command with "-"):
  { "key": "cmd+f2", "command": "-vinel.macroRecordToggle" },
  { "key": "cmd+f3", "command": "-vinel.macroPlayLast" }
]

Notes:

• Keep "when": "editorTextFocus" so the shortcuts work in every mode (that's what lets you start/stop recording mid-Insert). To restrict a shortcut to Normal mode only, use "when": "editorTextFocus && vinel.mode == 'normal'".
• A numeric prefix for playback works in Normal mode regardless of the key you choose: type the count, then fire your playback combo (5 → replay 5×).
• Your keybindings.json always wins over ViNEL's defaults, so you don't have to disable a default before rebinding — the -command lines above are only if you want the old key to do nothing.

Rebinding anything else

The same recipe works for any ViNEL command — search "ViNEL" in the Keyboard Shortcuts UI to see them all, or bind by command id in JSON. A few handy ids: vinel.enterVisualBlock (blockwise Ctrl-V — rebind if you want Ctrl-V back as Paste on Windows/Linux), vinel.exCommand (:), vinel.repeatChange (.).

Leader & custom mappings

A leader mapping is simple: press a leader key, then a short letter sequence, to run any command — e.g. Space then f opens the file picker. It's how Neovim users bind their most-used actions. ViNEL doesn't invent a mapping language for this; you use native VS Code chord keybindings gated to Normal mode, so they sync with the Keyboard Shortcuts UI like everything else. Space is the conventional leader and ViNEL keeps it free (bare Space in Normal does nothing), but any first key works.

Command Palette (Cmd/Ctrl+Shift+P) → Preferences: Open Keyboard Shortcuts (JSON). Each entry reads as: "key" = your leader sequence · "command" = what to run · "when" = vinel.mode == 'normal' (so it only fires in Normal):

[
  // <leader> = Space
  { "key": "space f",   "command": "workbench.action.quickOpen",  "when": "editorTextFocus && vinel.mode == 'normal'" },
  { "key": "space w",   "command": "workbench.action.files.save", "when": "editorTextFocus && vinel.mode == 'normal'" },
  { "key": "space g g", "command": "workbench.view.scm",          "when": "editorTextFocus && vinel.mode == 'normal'" },
  // a leader key can fire ViNEL's own commands too
  { "key": "space m",   "command": "vinel.macroPlayLast",         "when": "editorTextFocus && vinel.mode == 'normal'" }
]

Finding the command to bind

Every action in VS Code has a command id — the string you put in "command". To find one:

1. Open Keyboard Shortcuts (Cmd/Ctrl+K Cmd/Ctrl+S).
2. Search in plain words — "save", "find files", "toggle terminal", "format document", or "ViNEL" for ViNEL's own.
3. Right-click the matching row → Copy Command ID and paste it as "command".

That's the whole trick — anything you can find in Keyboard Shortcuts, you can put behind a leader key: built-in commands, other extensions' commands, or ViNEL's (vinel.macroPlayLast, vinel.exCommand, …).

• Change your leader by swapping the first key (,, \, …) in each entry.
• Sequences are just multi-key chords — space g g, pressed in order.
• Your keybindings.json outranks ViNEL's defaults, so these take over Space in Normal automatically (see Customizing keybindings).

Design note: text objects seek forward (across lines)

If the cursor isn't already inside/on a bracket or quote, di[ / ci" seek forward through the document to the next one and act on its matched pair — so they work from anywhere, not only when you're on top of the delimiter. An enclosing pair always wins over a later one.

This is a deliberate choice. Strict vanilla Vim only acts on an enclosing pair (and beeps otherwise); ViNEL matches the plugin-augmented Neovim experience (targets.vim / mini.ai style) instead, because it's more useful in practice. So from far above a lone bracket, di[ will travel down to that next occurrence — by design.

Requires VSCodeVim disabled

If VSCodeVim is installed it claims the same keys through its own context, and which one fires becomes unpredictable. Disable or uninstall it:

code --uninstall-extension vscodevim.vim

Building

npm install
npm run compile
npm run package                    # produces a .vsix
code --install-extension vinel-0.0.1.vsix --force

Uninstalling & resetting

Uninstalling removes ViNEL and all of its commands and default keybindings automatically. It contributes no settings and writes nothing to disk, so a reinstall always starts clean — handy if anything ever gets into a weird state. Your own keybindings.json (leader mappings, custom binds) is your file and is left untouched; keep a copy (or track your VS Code config in git) so you can restore it after a reinstall.

Not built yet

A few niceties remain: numbered / system-clipboard registers ("0, "+), the ( / ) sentence motions, and treesitter function/class objects (if/af). Everything else documented above — modes, motions, operators, text objects, marks & named registers, Ex-commands, macros, leader mappings, surround, and case operators — is built and native, with no companion extension required.

Feedback & bug reports

• Bugs / feature requests: open an issue at https://github.com/andrew-booshartig/vinel-vscode/issues.
• On the Marketplace: the extension page's Q&A tab and Ratings & Review section both reach the publisher.
• Please include your OS, VS Code version, and steps to reproduce.

Support

If ViNEL saves you time, you can support development ☕ Buy me a coffee