[DOCS] Vim mode docs omit Esc-in-INSERT interrupt behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/interactive-mode

Section/Topic

The Vim editor mode section, plus related Esc/interrupt guidance for terminal sessions when Claude is running.

Current Documentation

The docs currently say:

In interactive-mode, the Vim mode table says Esc will "Enter NORMAL mode" from INSERT. In keybindings, the Vim mode interaction section says: "The Escape key in vim mode switches INSERT to NORMAL mode; it does not trigger chat:cancel". In terminal-guide, the getting-started instructions say: "Press Esc to interrupt Claude if it's running."

What's Wrong or Missing?

Changelog v2.1.119 changed this behavior to: "Vim mode: Esc in INSERT no longer pulls a queued message back into the input; press Esc again to interrupt".

The current docs do not explain the running-turn behavior when Vim mode is enabled:

A. Missing INSERT-mode interrupt behavior

When Vim mode is enabled and the prompt is in INSERT, the first Esc only leaves INSERT mode. The docs do not say that users must press Esc again to interrupt the running turn.

B. Missing queued-message behavior

The docs do not mention that Esc in Vim INSERT mode no longer pulls a queued message back into the input. That behavior matters for users who queue follow-up prompts while Claude is still working.

C. Conflicting guidance across pages

terminal-guide still presents Esc as a one-step interrupt, while interactive-mode and keybindings describe Vim INSERT behavior separately. Without a combined explanation, the actual behavior in Vim mode is hard to infer.

Suggested Improvement

Add a short note to interactive-mode near the Vim editor mode section, and cross-reference it from terminal-guide and keybindings.

Suggested wording:

When Vim mode is enabled and Claude is running, pressing Esc in INSERT mode switches the prompt to NORMAL mode. Press Esc again to interrupt the running turn. If you want to edit a queued message instead, use Up arrow to pull it back into the input.

This would make the post-v2.1.119 behavior explicit and remove ambiguity around queued messages versus interrupts.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/interactive-mode | 39, 105-113 | Esc + Esc is documented for rewind/summarize, and Vim mode says Esc enters NORMAL from INSERT |
| https://code.claude.com/docs/en/keybindings | 433-438 | Explains that Vim-mode Esc switches INSERT to NORMAL and does not trigger chat:cancel |
| https://code.claude.com/docs/en/terminal-guide | 55, 130 | Generic startup guidance says Esc interrupts Claude if it's running |
| https://code.claude.com/docs/en/terminal-config | 115-120 | Vim Mode subset lists Esc only as the INSERT → NORMAL mode switch |

Total scope: 4 pages affected

Source: Changelog v2.1.119

Changelog entry:

Vim mode: Esc in INSERT no longer pulls a queued message back into the input; press Esc again to interrupt