Vim Mode Kept Fighting Esc? Jump Matching Brackets and Leave INSERT Cleanly.

At a glance

• Claude Code's vim mode now has %, which jumps to the matching bracket, alone or with d, c or y.
• Esc now leaves INSERT reliably on a busy machine, and a typed AskUserQuestion answer no longer vanishes when you press Esc.
• You need v2.1.301. At 6:00 AM ET on Friday 16 October, latest and next had it, but stable was still at v2.1.292.

You turn on vim mode because you want motions in the prompt, then Esc sometimes leaves you stuck in INSERT, or it wipes the answer you just typed into an AskUserQuestion field. Bracket jumps were missing too, so deleting through a balanced pair meant hunting with f and counting. Claude Code v2.1.301 closes those gaps.

Why it matters

When Esc fails to leave INSERT on a slow or busy machine, every motion that should be a one keystroke fix turns into a fight with the prompt. And when Esc on an AskUserQuestion free text field discarded your answer, "leave INSERT" and "cancel" were the same key, so a reflex cost you the text.

The v2.1.301 changelog fixes both. Vim mode no longer sometimes stays in INSERT after Escape on a slow or busy machine. The AskUserQuestion free text field now supports vim NORMAL mode, and Esc cancels only from NORMAL, so the first Esc leaves INSERT and a second one cancels.

The new % motion is the other half. Matching brackets are how you yank, change or delete a balanced expression without counting characters. The docs say % jumps to the matching (), [] or {}, and if the cursor is not on a bracket, it starts from the next bracket on the current line. Pair it with d%, c% or y% and the operator runs from the cursor through that match.

How to turn on vim mode and jump matching brackets

1. Check your build with claude --version. The docs list v2.1.301 as the floor for % and its operators, and both Esc fixes are in the v2.1.301 changelog. If you are on stable, you do not have them yet: at 6:00 AM ET Friday that channel was still at v2.1.292. You can wait for stable to move, or, on an npm install, deliberately pin the release that latest and next carried at that check with npm install -g @anthropic-ai/claude-code@2.1.301. Do not mix npm and native installs on one machine.
2. Enable vim mode. Run /config, open Editor mode and choose vim, or set editorMode in your user settings file at ~/.claude/settings.json:

{
  "editorMode": "vim"
}

1. In the prompt, type a short expression with brackets, press Esc to enter NORMAL, put the cursor on an opening (, [ or {, and press %. The cursor should land on the matching bracket. From the same spot, try y% to yank through the pair or d% to delete it.
2. Now put the cursor somewhere before a bracket on the same line and press % again. Per the docs, it starts from the next bracket on that line.
3. Check Esc. From INSERT, press Esc once and confirm you can move with h and l. In an AskUserQuestion free text field, type an answer, press Esc once, and the text should stay while you are in NORMAL. Press Esc again from NORMAL to cancel.
4. Optional: if you prefer a two key sequence such as jj to leave INSERT, the docs cover vimInsertModeRemaps (v2.1.208 or later). It is read only from user settings, the --settings flag and managed settings, so a project's .claude/settings.json cannot remap your keys.

Enter still submits in INSERT, unlike stock Vim. Use o or O in NORMAL, or Ctrl+J, for a newline.

Gotchas

%, d%, c% and y% need v2.1.301, so a build from stable at v2.1.292 will not have them until that channel moves. Vim motions are not remappable through the keybindings file; only two key INSERT sequences in vimInsertModeRemaps are, and they target Escape. Block wise visual mode with Ctrl+V is not supported, though character wise v and line wise V are. Claude Code keeps your vim mode and cursor position when you open and close /config or toggle the transcript viewer with Ctrl+O, so you come back in the mode you left. To turn vim mode off, set Editor mode back to normal.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever AI you use.