Graceful modal editing for VS Code.

Waltz is a modal editing extension for VS Code that emphasizes smooth integration with VS Code's native features. It provides Vim-inspired keybindings while fully embracing VS Code's philosophy—from multiple cursors to native selection handling.

• Based on: jpotterm/vscode-simple-vim - The original codebase that made this project possible
• Philosophically inspired by: 71/dance - A Kakoune-inspired modal editor that influenced Waltz's design philosophy around selection-first editing and VS Code-native integration

Waltz aims to provide a graceful editing experience that feels natural in VS Code, like a waltz that flows smoothly with the editor's native capabilities.

Unlike traditional Vim emulation that fights against VS Code's architecture, Waltz embraces it:

• VS Code-native approach: Works seamlessly with VS Code's selection model, cursor behavior, and editing primitives
• Multiple cursors first-class: Full support for VS Code's multiple cursor features instead of macros
• Smooth integration: Designed to complement, not replace, VS Code's built-in features
• Modal editing without the baggage: The power of modal editing without strict Vim compatibility constraints

Waltz operates in four distinct modes:

Operators act on text defined by motions or text objects. Used in Normal mode by typing an operator followed by a motion/text object.

Motions move the cursor in Normal or Visual mode. In Visual mode, one side of the selection stays anchored while the other side moves.

Text objects select ranges of text for use with operators. They must follow an operator in Normal mode.

All motions can be used as text objects with operators. For example:

• dw - Delete to next word
• d$ - Delete to end of line
• dj - Delete current and next line

Vim-like surround operations for adding, deleting, and changing surrounding characters.

Supported surround characters: (), {}, [], <>, ", ', `, and bracket aliases b for (), B for {}

Miscellaneous editing commands.

In Insert mode, you can customize additional editing commands:

Integrate with VS Code's language intelligence features. All available in Normal mode unless noted.

Waltz prioritizes smooth integration with VS Code over strict Vim compatibility. Here are key differences:

• No macros: Use VS Code's multiple cursors instead. Place cursors with Cmd+d, Cmd+Alt+Down, or Alt+Click to edit all locations simultaneously.

• No . (repeat) command: Use multiple cursors or repeat the command instead.

• No count prefix: In Vim you can use counts like 3w. In Waltz, just repeat the command or use a command that accomplishes your goal in one action.

• Cursor can exceed line length: In Normal mode, the cursor can go one position past the last character due to VS Code's selection model.

• No registers: The d operator copies to clipboard when deleting, so deleted text is available for pasting.

• Different f and t motions:

  • t takes one character
  • f takes two characters (like vim-sneak plugin)
  • t works like Vim's t in Normal mode but like f in Visual mode

• No / (search) command: Use the f motion or VS Code's native find (Cmd+f).

• No jump list: Use VS Code's native navigation with Ctrl+- and Ctrl+_ instead of Ctrl+o and Ctrl+i.

• No marks: Use VS Code's split view with Cmd+1 and Cmd+2 to navigate between locations, or Ctrl+- to jump back.

The y (yank) operator temporarily highlights the yanked text to make it obvious what you're copying. Customize the highlight color:

{
    "waltz.yankHighlightBackgroundColor": "#F8F3AB"
}

Extend Waltz with custom key bindings via the waltz.customBindings setting:

{
    "waltz.customBindings": [
        {
            "keys": ["space", "f"],
            "modes": ["normal"],
            "commands": [
                {
                    "command": "workbench.action.quickOpen"
                }
            ]
        },
        {
            "keys": ["space", "w"],
            "modes": ["normal"],
            "commands": [
                {
                    "command": "workbench.action.files.save"
                },
                {
                    "command": "workbench.action.closeActiveEditor"
                }
            ]
        }
    ]
}

• keys (required): Array of strings for the key sequence (e.g., ["g", "d"])
• commands (required): Array of VS Code commands to execute sequentially, each with:
  • command (required): The VS Code command ID
  • args (optional): Arguments to pass to the command
• modes (optional): Array of modes where binding is active ("normal", "visual", "visualLine", "insert"). If omitted, applies to all modes.

Custom bindings are checked before default bindings, allowing you to override built-in mappings.

Many of Waltz's actions use symbolic keybindings that can be remapped via your VS Code keybindings.json. This allows you to customize frequently-used actions without modifying the extension itself.

Default mappings for half-page movement can be customized:

{
    "key": "ctrl+d",
    "command": "waltz.send",
    "args": {
        "keys": "<Waltz>half-page-down"
    },
    "when": "editorTextFocus && waltz.mode != 'insert'"
},
{
    "key": "ctrl+u",
    "command": "waltz.send",
    "args": {
        "keys": "<Waltz>half-page-up"
    },
    "when": "editorTextFocus && waltz.mode != 'insert'"
}

You can remap these to different keys by modifying the "key" field. The action names (<Waltz>half-page-down, <Waltz>half-page-up) remain the same.

Copy, cut, and paste operations can be customized:

{
    "mac": "cmd+c",
    "win": "ctrl+c",
    "linux": "ctrl+c",
    "command": "waltz.send",
    "args": {
        "keys": "<Waltz>copy"
    },
    "when": "editorTextFocus && waltz.mode != 'insert'"
},
{
    "mac": "cmd+x",
    "win": "ctrl+x",
    "linux": "ctrl+x",
    "command": "waltz.send",
    "args": {
        "keys": "<Waltz>cut"
    },
    "when": "editorTextFocus && waltz.mode != 'insert'"
},
{
    "mac": "cmd+v",
    "win": "ctrl+v",
    "linux": "ctrl+v",
    "command": "waltz.send",
    "args": {
        "keys": "<Waltz>paste"
    },
    "when": "editorTextFocus && waltz.mode != 'insert'"
}

The available actions are:

• <Waltz>copy - Copy (yank) selection or line
• <Waltz>cut - Cut (delete) selection or line
• <Waltz>paste - Paste from clipboard

Place cursors on multiple lines and use motions to select together:

1. Position cursor with Cmd+d or Cmd+Alt+Down
2. Use motions like w, $, etc. to navigate all cursors
3. Execute operators like d, y, c to edit all positions

• diw - Delete inner word
• ci" - Change inside double quotes
• ya{ - Yank around braces
• ds( - Delete surrounding parentheses

• f, then ; - Find commas and repeat forward
• t( then , - Find before ( and repeat backward
• Great for navigating through code with known character patterns

MIT License - See LICENSE.txt for details.