Lesson 1 — Modes

An agent has just printed forty lines and the path you need is somewhere in the middle. You reach for the arrow keys, and the terminal sends them to the agent. That is the problem modes solve: for a moment, the keyboard stops being a way of typing and becomes a way of moving.

Modes are the one idea everything else in Vim rests on. Learn this page and the rest of the course is vocabulary.

The one idea

In most editors every key means "insert this character". Vim splits that in two.

• In insert mode, keys are text. Typing works exactly the way it always has.
• In normal mode, keys are commands. w is not the letter w, it is "next word". y is not a letter either, it is "copy".

That is the whole trade. You give up one keypress — Esc — and in exchange every letter on the keyboard becomes a verb you can reach without a modifier, a menu or a mouse. Your hands never leave the home row, which is why it stays fast on a laptop and why it works at all on a phone.

Where this works: both halves of Circuitry. In a code editor with Vim mode on you get full modal editing. In a terminal — including one running a CLI coding agent — you get the same modes aimed at reading, searching and copying, plus editing the line you are currently typing. Turn them on in Settings → Code Editing → Vim Mode (⌘⇧V) and Settings → Terminal → Vim keys, or from a terminal's own right-click / long-press menu, where Vim keys is the last item.

Which mode you start in

This catches everyone once, so it is worth saying plainly.

The two are not symmetrical, and it matters. In a code editor you must press i before you can type anything at all. In a terminal you need press nothing: it behaves exactly as it always did, and you type your command straight in. Esc is not a toll on the way in — it is what you press on the occasions you want to stop typing and go and look at something.

The modes

Getting back to typing

Six keys return you to insert mode, and they differ only in where they put you.

In a terminal, o and O simply return you to typing — there is no new line to open at a prompt.

Two things worth knowing early about returning to typing in a terminal:

You start typing where the cursor is. Walk back to a typo four words into the command you are typing, press i, and you are editing at that spot — not back at the end of the line. a puts you one character further on, and I and A do the same for the start and end of the line.

The view comes back with you. If you have scrolled up into the output, i drops you back at the live prompt with your half-typed command intact.

Where this works: all six keys, both halves.

Selecting: visual and visual line

v starts a selection at the cursor. Every motion after that grows it: vw takes a word, v$ takes the rest of the line. V selects whole lines from the start. Press Esc to drop the selection, or v again to cancel it.

Then do something with it: y copies it, d deletes it, c replaces it. Lesson 3 covers the verbs.

o swaps which end you are extending. Start a selection, overshoot, and instead of beginning again you press o and pull the other end back. In visual mode o has nothing to do with opening a line. On a phone it is the difference between fixing a selection and starting it again.

One more visual-mode rule that will make sense in Lesson 4: inside a selection, i and a do not return you to typing. They begin a text object — viw means "select inner word".

Where this works: v, V and motions in both halves. In a terminal, deleting or changing a selection only works on the line you are typing — though where the terminal wrapped that line over several rows, a selection may cross them. A selection reaching up into the output above can still be copied, just not deleted.

Esc, and the Esc ladder

In a code editor Esc means one thing: go to normal mode.

In a terminal Esc is a ladder, because the program below you also wants Esc — to interrupt a coding agent, or to leave a menu in a full-screen program.

1. Esc from insert mode → normal mode. Nothing is sent to the program. This is a local change of mind.
2. Esc from visual mode → normal mode. The selection is dropped. Still nothing sent.
3. Esc again from normal mode → a real Esc goes to the program. You stay in normal mode.

So Esc Esc is how you interrupt an agent mid-turn.

Knowing which mode you are in

You are never guessing.

• In a terminal, normal mode paints a block on the cursor and shows a NORMAL badge in the corner. Tapping that badge always returns you to typing — it is the escape hatch, and you do not need to know which mode you got stuck in to use it.
• In a code editor, a slim status bar sits at the bottom showing --INSERT-- or --VISUAL-- and echoing commands as you type them. In normal mode it is empty, which is its own signal.

There is one more piece of good news for reading: while a terminal is in normal mode, output arriving from the program will not yank the screen back to the bottom. You can read something twenty lines up while an agent keeps working.

Esc inside a workflow node

Workflow nodes have their own Esc meaning — hand focus back to the canvas — so with Vim mode on it becomes mode-aware:

1. In insert or visual mode, Esc returns you to normal mode. You stay in the editor.
2. In normal mode, Esc leaves the editor and returns focus to the node.

A reflexive extra Esc therefore never costs more than a click back in.

Try it

1. Open a terminal and turn on Vim keys: right-click or long-press in it, then choose Vim keys (the last item).
2. Type a command at the prompt but do not press Enter. You are in insert mode — nothing has changed yet.
3. Press Esc. A block appears on the cursor and a NORMAL badge appears in the corner.
4. Press k a few times to walk up into the output. You are reading now, and nothing has been sent to the program.
5. Press Esc again. That one reached the program. If a coding agent had been mid-turn, you would just have interrupted it.
6. Press v, then l a few times to grow a selection. Press o, then l again — you are now growing the other end.
7. Press Esc to drop the selection, then i to return to typing. The view comes back to the prompt and your half-typed command is still there.
8. In a code editor with Vim mode on, press i, type a word, and press Esc — watch --INSERT-- appear and disappear in the status bar.

You now know: normal mode reads, insert mode types, visual mode selects — and in a terminal, Esc twice is how you reach the program.

Related

• Vim Mode — the full command reference
• Terminals
• CLI Coding Agents
• Code Editor

← Learn Vim · Lesson 2 — Moving Around →