Claude Code vim mode: how to turn it on and every key it supports

What is vim mode in Claude Code?

Claude Code vim mode is a modal editing mode for the prompt box: you turn it on with /config then Editor mode, or with "editorMode": "vim" in your settings, and you get NORMAL, INSERT and VISUAL modes with familiar motions like hjkl, w, ciw and dd. It only changes how you edit the text you type to Claude. It does not affect the conversation output above the prompt.

If you write long prompts, fix typos in the middle of a sentence, or paste code you then want to trim, vim mode saves a lot of arrow-key travel. The official interactive mode reference lists every supported key, and this guide walks through them in a more practical order.

How do you turn on vim mode now that /vim is gone?

Older tutorials tell you to type /vim. That command no longer exists. The commands reference lists /vim as "Removed in v2.1.92" and points to /config instead.

You have two ways to turn it on today:

1. From inside Claude Code. Run /config, find Editor mode, and change it to vim.
2. In a settings file. Add editorMode to your user settings at ~/.claude/settings.json.

{
  "editorMode": "vim"
}

The editorMode setting takes two values, "normal" (the default) and "vim". To turn vim mode off, set it back to normal in /config or in the file.

Because it is a personal preference, keep it in your user settings rather than a project's committed .claude/settings.json. The settings guide explains which file applies to whom.

How do you switch between modes?

You start in INSERT mode, typing normally. Press Esc to go to NORMAL mode, where letters become commands. From NORMAL mode, these keys take you back to typing or into a selection:

One detail trips up vim users: Enter still submits in INSERT mode. Claude Code doesn't treat Enter as "new line" the way vim does. Use o or O from NORMAL mode, or Ctrl+J, when you want a line break inside a multi-line prompt.

Claude Code also remembers your mode and cursor position when you open the transcript viewer with Ctrl+O or open a panel such as /config. If you left the prompt in NORMAL mode, it is still in NORMAL mode when you come back.

Which motions and edits work in NORMAL mode?

Claude Code supports a solid subset of vim, not the full editor. Here is what the docs list.

Moving around:

When the cursor is already at the top or bottom of the input, j/k (and the arrow keys) move through your prompt history instead.

Editing:

Operator and motion pairs such as df], dt,, dgg, dG, dj and dk also work, and d0, c0 and y0 act from the cursor back to the start of the line on v2.1.281 or later.

Do text objects and visual mode work?

Yes, both work. Text objects combine with d, c and y, so ciw changes the word under the cursor and di" empties a quoted string.

In visual mode (v or V), motions extend the selection and operators act on it: d or x deletes, y yanks, c or s changes, p replaces the selection, ~, u and U change case, > and < indent, J joins and o swaps the cursor and anchor. Block-wise visual mode with Ctrl+V is not supported.

How do you map jj or jk to Escape?

Many vim users never reach for the Escape key. Claude Code supports this with the vimInsertModeRemaps setting. This user settings file turns on vim mode and maps jj to Escape:

{
  "editorMode": "vim",
  "vimInsertModeRemaps": { "jj": "<Esc>" }
}

The rules are strict:

• Each key is exactly two printable characters, and "<Esc>" is the only supported target. Other entries are ignored.
• Type the second character within one second of the first and Claude Code drops both and switches to NORMAL mode. Pause longer, or type a different key, and both characters stay as normal text, so you can still type a word that contains the pair.
• Claude Code reads this setting only from your user settings, the --settings flag and managed settings. A project's .claude/settings.json or .claude/settings.local.json can't set it, so a repository you clone can't remap your keystrokes.

How does vim mode work with other shortcuts?

Vim mode and Claude Code's keybindings run side by side. The keybindings docs spell out how they interact:

• Vim mode handles cursor movement, modes and motions in the text box. Keybindings handle actions such as submitting or toggling panels.
• Esc in vim mode switches INSERT to NORMAL. It doesn't trigger chat:cancel, the action that cancels the current input when you press Esc in normal mode.
• Most Ctrl shortcuts pass straight through vim mode to the keybinding system.
• In NORMAL mode, ? shows the help menu and / opens history search, the same as Ctrl+R in normal mode.
• Vim keys themselves can't be remapped in ~/.claude/keybindings.json.

There is one more case to know. When Claude asks you a question and you type your own answer in the Other row, the first Esc only drops you into NORMAL mode. Press Esc again to cancel the question, or bind a Ctrl or Alt key to select:cancel for a one-key cancel.

For the full list of non-vim shortcuts, see the Claude Code keyboard shortcuts guide.

What if you want the real vim?

Vim mode covers quick prompt edits. For a long prompt, open it in your actual editor: press Ctrl+G (or the readline-style Ctrl+X Ctrl+E) and Claude Code opens the prompt in your default text editor. Save and close, and the text comes back to the prompt box. If that editor is Vim or Neovim, you get your full configuration, plugins and all.

Long prompts are also the ones worth keeping. Kipt stores the prompts you reuse as Markdown in a private GitHub repo you own, with {{name}} blanks for the parts that change, so a carefully written prompt doesn't vanish when the session ends.

Quick checklist

• Turn it on with /config, then Editor mode, or "editorMode": "vim".
• Ignore old advice about /vim: it was removed in v2.1.92.
• Use o, O or Ctrl+J for new lines, because Enter submits.
• Add vimInsertModeRemaps in user settings for jj or jk.
• Use Ctrl+G when you need the full editor.

The terminal setup guide covers the rest of the terminal side, such as Shift+Enter and Option as Meta on macOS.