OmniscioGuidesClaude Code vim mode
Claude Code vim mode
If your fingers already reach for dw and ci", vim mode makes the Claude Code prompt behave the way a vim buffer does. It is a few keystrokes of setup and a much larger set of documented keys to learn.
This page covers both ways to turn it on, the mode switches, the motions and edits Anthropic documents, the jj remap, and the mistakes that make people think the setting is broken.
Last checked against Anthropic's interactive mode documentation on November 17, 2026. By the Omniscio team. Updated .
On this page
- What it changes
- Turn it on
- Switching modes
- Moving around
- Editing
- Text objects and visual mode
- Make jj act as Escape
- Limits and mistakes
Every key below is one Anthropic documents in its interactive mode reference. If you want the non-vim shortcuts, the keyboard shortcuts guide covers those.
What it changes
Vim mode changes how the prompt box takes your keystrokes. In NORMAL mode a letter is a command, so dw deletes a word instead of typing the letters d and w. In INSERT mode the box types as usual.
It does not change the code Claude writes, and it does not affect the editor you open files in. Everything here is about the line you are typing to Claude.
That is why it is worth learning even if you have never used vim in a terminal, and why it is worth skipping if you write long prose to Claude with arrow keys and expect them to work the same.
Source: the vim-editor-mode section of Anthropic's interactive mode reference, read November 17, 2026.
Turn it on
The menu route is /config, then Editor mode, switched to vim. That is the whole setup, and the menu writes the setting for you.
The file route is one key in ~/.claude/settings.json. It is the one to use when you want the same behaviour in every project and every new session:
{
"editorMode": "vim"
}To turn vim mode off, switch Editor mode back in /config, or remove the editorMode key from the file.
Where that file lives, and which other settings files can override it, is its own topic: where settings.json lives.
Sources: the enable line of the vim-editor-mode section of Anthropic's interactive mode reference, and the editorMode example in it, read November 17, 2026.
Switching modes
Esc or Ctrl+[ takes you to NORMAL mode from INSERT or VISUAL. On a terminal that uses the Kitty keyboard protocol, Anthropic notes Ctrl+[ needs Claude Code v2.1.242 or later.
Six keys take you back to INSERT, depending on where you want the cursor. i inserts before the cursor and a inserts after it. I inserts at the beginning of the line and A at the end.
o opens a new line below and O a new line above, both in INSERT mode. From NORMAL, v starts a character-wise selection and V a line-wise one.
One behaviour surprises people coming from a terminal editor. In NORMAL mode, when the cursor is already at the beginning or end of the input, j, k and the arrow keys move through your command history instead.
Source: the mode-switching and navigation tables of Anthropic's interactive mode reference, read November 17, 2026.
Moving around
The basics are the ones you expect: h, j, k and l move, and Space also moves right. w, e and b jump by word.
For the line itself, 0 goes to the beginning, $ to the end, and ^ to the first non-blank character. gg goes to the beginning of the whole input and G to the beginning of its last line.
The single-character jumps are all there: f and F jump to the next or previous occurrence of a character on the line, and t and T stop just before or after it. ; repeats the last one and , repeats it backwards.
% jumps to the matching bracket, from the next bracket on the line when the cursor is not on one, and needs v2.1.301 or later.
/ opens reverse history search, the same as Ctrl+R. Anthropic's hint for reaching the command menu from there: press Esc, then i, then /.
Source: the navigation table of Anthropic's interactive mode reference, read November 17, 2026.
Editing
Deleting follows vim: x deletes a character, dd a line, D to the end of the line, and dw, de or db by word. df{char} and dt{char} delete through or up to the next occurrence of a character.
Changing mirrors it: cc for a line, C to the end of the line, cw, ce and cb by word, s to substitute a character and S a whole line. Each of those ends in INSERT mode.
Copying uses yy or Y for a line and yw, ye, yb for words. p pastes after the cursor and P before it.
>> and << indent and dedent, J joins lines, u undoes, and . repeats the last change. That last one is the reason to learn vim mode at all: a failed prompt can be fixed and re-run without retyping it.
Source: the editing table of Anthropic's interactive mode reference, read November 17, 2026.
Text objects and visual mode
Text objects work with d, c and y: iw and aw for a word, iW and aW for a whitespace-delimited WORD, and inner and around forms for double quotes, single quotes, parentheses, brackets and braces.
So ci" replaces the text inside the nearest pair of double quotes, and da( removes a parenthesised phrase including its brackets. For a prompt that quotes a file path or an error string, that is a real saving.
In visual mode, v selects characters and V selects lines, and motions extend the selection. d deletes it, y yanks it, c changes it, and p replaces it with the register contents.
~, u and U toggle, lowercase or uppercase the selection, and > and < indent or dedent whole lines. o swaps the cursor and the anchor.
One gap: block-wise visual mode with Ctrl+V is not supported. Anthropic states that plainly rather than leaving you to discover it.
Source: the text-objects and visual-mode tables of Anthropic's interactive mode reference, read November 17, 2026.
Make jj act as Escape
vimInsertModeRemaps maps a two-key INSERT-mode sequence to Escape. This example turns vim mode on and maps jj in one file:
{
"editorMode": "vim",
"vimInsertModeRemaps": { "jj": "<Esc>" }
}Each key is exactly two printable characters typed in sequence, and "<Esc>" is the only supported target. An entry with a different length or target is ignored, without an error.
The timing matters. Typing the first character inserts it normally; pressing the second within one second removes that pending character and switches to NORMAL, leaving neither character in your input.
After that one-second window, or if a different key follows, both characters stay as literal text. That is deliberate: it is how you still type a word containing the sequence by pausing between the two keys.
This setting is read from your user settings file, the --settings flag and managed settings only. Entries in a project's .claude/settings.json or .claude/settings.local.json are ignored, so a repository you clone cannot remap your keystrokes.
Source: the remap-INSERT-mode-key-sequences section of Anthropic's interactive mode reference, read November 17, 2026.
Limits and mistakes
The most common mistake is putting the setting in the wrong file. If jj does nothing after you commit it to a project's settings, that is exactly the rule described above: move it to your user settings file.
The second is forgetting which mode you are in. A prompt that types capital letters, or nothing at all, is usually NORMAL mode taking your keys as commands. Press i and it types again.
Third: vim mode does not bring block-wise visual mode, and the bracket keys arrived in v2.1.301. On an older build % and d% do something else, or nothing.
If you use the VS Code extension instead of the terminal, its prompt box has its own shortcuts, which the VS Code guide covers.
Sources: the vim-mode notes and the general-controls table of Anthropic's interactive mode reference, read November 17, 2026.
Running several sessions at once
Vim mode is a per-machine preference, so every session you start shares it. Omniscio, the desktop app we make for running many Claude Code sessions at once, puts those sessions in one window with a sidebar instead of separate terminals.
It is free to use with up to 8 projects. Pro is $20/month or $192/year, and neither plan includes an AI allowance.
The multi-session guide compares the ways to run more than one, and the terminal flickering guide covers a display that keeps redrawing while you type.
Where these answers come from
- Anthropic, Interactive mode: the vim editor mode section, its mode-switching, navigation, editing, text-object and visual-mode tables, the
vimInsertModeRemapssetting and its one-second window, and the note that block-wise visual mode is unsupported. Read November 17, 2026. - Anthropic, Settings: the
editorModefield and which settings files Claude Code reads. Read November 17, 2026.
The two version numbers here (`v2.1.242`, `v2.1.301`) are the ones Anthropic's own page named when it was read on November 17, 2026. Read it again before trusting an older copy.
Common questions
How do I turn on vim mode in Claude Code?
Run /config and select Editor mode, or put "editorMode": "vim" in ~/.claude/settings.json. The setting file route is what makes it stick across sessions; the menu writes the setting for you.
Why is my jj mapping ignored in Claude Code?
Because vimInsertModeRemaps is read only from your user settings file, the --settings flag and managed settings. An entry in a project's .claude/settings.json or .claude/settings.local.json is ignored, so a checked-out repository cannot remap your keystrokes.
What does the jj mapping do in Claude Code?
It maps a two-key INSERT-mode sequence to Escape, so typing jj returns you to NORMAL mode. Typing the first character inserts it normally, and pressing the second within one second removes the pending character and switches modes, leaving neither character in your input.
Does Claude Code support block-wise visual mode in vim mode?
No. Character-wise selection with v and line-wise selection with V are supported, but block-wise visual mode with Ctrl+V is not.
How do I get out of vim mode's NORMAL mode and back to typing?
Press i to insert before the cursor, a to insert after it, A to insert at the end of the line, or o for a new line below. All of them switch to INSERT mode, where ordinary typing works again.
In vim mode, how do I cancel a question Claude asks?
Press Esc twice while typing your own answer in the Other row of the question. Anthropic also documents binding a single key to cancel the question if you would rather use one keypress.
Keep your keys, add a window for every session
Omniscio runs many Claude Code sessions side by side, outside the terminal. The features page lists what it does today.