Learn Vim

A short course in the keyboard language that turns finding, copying and fixing text into a handful of keystrokes — taught from nothing, using only the commands Circuitry actually supports.

Vim's keybindings are decades old and still the fastest way anyone has found to move around text without touching a mouse. Circuitry speaks them in two places: code editors, where you get full modal editing, and terminals — including the panes running CLI coding agents — where you get modal navigation over everything on the screen. Same grammar, two jobs.

If you already know Vim and just want the tables, go to the Vim Mode reference. If you don't, start here.

What Vim actually is

Vim has modes. In an ordinary editor every key you press types a character. Vim splits that in two. In insert mode, typing works exactly the way you expect. In normal mode — where Vim starts — the letter keys are commands instead: j moves down a line, w jumps forward a word, x deletes a character. Esc takes you to normal mode; i takes you back to typing. That single idea is the whole barrier to entry, and it takes about a minute to cross.

Vim is a grammar, not a list of shortcuts. Commands read like tiny sentences: (count) (operator) (motion). d means delete and w means "one word forward", so dw deletes a word. y means yank — copy — so yw copies one. 3dw deletes three. Swap the motion for a text object and it keeps reading the same way: iw is "inner word", i" is "whatever is inside the quotes", so yi" copies the thing between the quote marks and ciw replaces the word you're sitting on. You are not memorising hundreds of shortcuts. You learn roughly twenty pieces, and every new verb multiplies with every noun you already have.

Your hands never leave the home row. No reaching for the arrow keys, no Home and End, no hand off to the mouse and back. Movement, selection, copying and searching all live under your fingers where they already are. That is why people who learn it don't go back — not raw speed on any one command, but never breaking the thread of what you were doing.

Why this matters more now, not less

It would be easy to assume that an AI writing your code makes a fast text editor beside the point. The opposite happens — and the reason is that you are doing a great deal of typing, in the one place that has never had any editing tools.

Directing a coding agent means writing long, careful prompts: the thing you want, the constraints, the file it lives in, the error you just got. You rewrite them mid-sentence. You paste a path in, change your mind, and take it back out. And you are often doing it in several sessions at once, each with its own agent waiting on you.

All of that goes into a terminal. A code editor gives you a whole toolkit for text like this — click anywhere, select a word, delete back, undo. A terminal input box gives you a cursor and a backspace key. This is what Vim keys bring to the terminal: the editing power a code editor already has, in the place you write your prompts.

• Fix the wrong word four words back: Esc, b, ciw, type the correction.
• Delete a pasted URL you have changed your mind about: diW.
• Clear a half-written prompt and start again: dd.
• Jump to the start of a long prompt to add a word: ^.

The other half is reading. Those same sessions print a great deal at you — a stack trace, a diff, a list of files it touched, a URL a dev server just printed, a block of explanation you want to quote back into the next prompt. Those errands all have one shape, find that thing, copy that thing, put it somewhere, which is exactly what motions and text objects are for.

• Search the output for a word with /, or find every other mention of the word already under the cursor with * — without typing it.
• Lift a path out of cannot open "src/x.ts" with yi".
• Copy the whole block an agent just printed — move up into it, then yip.
• Drop it back into the prompt with p.

The alternative for both halves is the mouse: reach across, drag carefully along a wrapped line, hope you didn't clip a character off either end, and hope the program doesn't repaint mid-drag. In a terminal that is scrolling, a drag is a race. A motion isn't.

Why it is transformative on a phone

Circuitry already puts the missing keys back: the key row above the soft keyboard carries esc, ctrl, tab and four auto-repeating cursor keys on its first page, and Home, End and the page keys on its Navigation page. Nothing is out of reach.

What is still slow is distance. A cursor key moves one character, or one row. Crossing a wrapped URL is forty taps, or a hold you have to time and then overshoot. That is the part Vim removes — not by adding keys, but by replacing a direction you repeat with a destination you name.

W steps over a whole URL. $ reaches the end of a wrapped line without a hold. / goes straight to a word you can see, and * finds the next mention of the one under the cursor without your typing it out on a soft keyboard. v plus a motion builds a selection with taps instead of a drag, and yiW copies that URL without selecting it at all.

The key row helps here too: it swaps to the Vim set the moment you enter normal mode, so / $ ^ * and the quote and bracket characters — the ones a phone buries two layouts deep — come to the front, with esc keeping its usual first slot. That's Lesson 7.

Where it works in Circuitry

Turn it on for editors and every code editor in the app becomes a Vim editor: code files, workflow nodes, side panels, CodeBook cells, page-source editors, the 3D scene editor. Turn it on for terminals and it works in standalone terminals, Terminal nodes, and the panes running CLI coding agents.

The terminal half has one rule worth learning up front: you can move, search, select and copy anywhere on the screen — you can only change the line you are currently typing. Lesson 6 has the detail.

What the learning curve really costs

Honestly: less than its reputation suggests, and the awkward part is front-loaded. The first hour is genuinely strange, because normal mode means your keyboard has stopped typing. After that it compounds.

The safety net is small and always in the same place: Esc gets you to normal mode, i gets you back to typing, and in a terminal you can tap the NORMAL badge in the corner to return to typing from anywhere, without knowing which mode you were stuck in.

Try it before you commit to anything

Six steps, one terminal, nothing changed on disk. Every key here is covered properly in the lessons below.

1. Open a terminal and turn Vim keys on for it: right-click, or long-press with a finger or Apple Pencil, and choose Vim keys — the last item in the menu.
2. Run something that prints a screenful. ls -la, a build, or a question to a coding agent all work.
3. Press Esc. A block appears on the cursor and a NORMAL badge appears in the corner. You are reading now, not typing.
4. Press k a few times to walk up into the output, then { and } to step between blocks of it. Nothing you have pressed has reached the program.
5. Find a line with a path or a URL on it, move onto it, and press yiW. The whole thing is now copied — in Vim's register and on your system clipboard.
6. Press p to drop it into your prompt — p is a normal-mode command, so it goes before you return to typing. Then i to carry on.

You now know: enough to read and copy anything out of a terminal without touching a pointer. Everything after this is more vocabulary for the same three moves.

The course

Seven lessons and a practice page. Each lesson opens with the errand it solves, marks which keys work in code editors, which in terminals and which in both, and ends with a Try it block you can do right now in a real terminal.

1. Lesson 1 — Modes — normal, insert and visual; the ways in and the ways out; the Esc ladder that lets you interrupt an agent.
2. Lesson 2 — Moving Around — h j k l, words versus WORDs, lines, screens and scrollback, and why a URL is one W but seven ws.
3. Lesson 3 — Operators, Counts and the Grammar — verb plus object: d c y, counts, single-key edits, case changes, and . to repeat.
4. Lesson 4 — Text Objects — inner and around; words, blocks, quotes and brackets. This is the lesson that makes people fast.
5. Lesson 5 — Search, Yank, Registers and Marks — the AI-era payoff: find it, copy it, keep three of them, paste them back.
6. Lesson 6 — Terminals and CLI Coding Agents — reading an agent's output, editing the line you're typing, and interrupting a turn.
7. Lesson 7 — Vim on a Phone — the key row, the count digits, and the errands that are only practical with a thumb once you have this.
8. Practice, Cheat Sheet and Where to Learn More — graduated drills, the full cheat sheet, and the handful of outside resources worth your time.

Start where it's cheapest

You do not have to turn it on everywhere at once. The two halves are separate switches, and the terminal switch can be flipped for one terminal from that terminal's own menu — right-click, or long-press with a finger or Apple Pencil, and choose Vim keys. Nothing else in the app changes.

That is the recommended way in. Spend a week using normal mode only to read and copy things out of output, where there is nothing to undo because you're not changing anything. Then turn it on in code editors, once the modes have stopped being a surprise.

Related

• Vim Mode — the full command reference for both halves
• Terminals
• CLI Coding Agents
• Code Editor
• The phone key row

Lesson 1 — Modes →