Lesson 7 — Vim on a Phone
The first six lessons make a desktop faster. A phone is where they pay off fastest — but not for the reason people expect.
Circuitry's key row above the soft keyboard already gives you the keys a phone keyboard leaves out: esc, tab and ctrl sit on its first page next to four auto-repeating cursor keys, and Home, End, Page Up and Page Down live on its Navigation page. You are not stuck.
You are, however, tapping. A cursor key moves one character or one row per press, and holding one to cross a long line is a race you usually overshoot. Normal mode changes the unit: W crosses a whole URL, $ goes to the end of the line, / goes to a word you can see, yiW copies the URL without your ever selecting it. Same thumb, one tap instead of forty.
Where this works: on a phone, in terminals — standalone terminals, Terminal nodes, and the panes running CLI coding agents. The key row described below re-stocks itself whenever one of those terminals is in normal mode. The code-editor half is the same grammar and the same keys; what belongs to terminals is the key row swap and the Esc ladder described below.
What a phone takes away, and what Vim hands back
| What it costs with the cursor keys | What it costs in normal mode |
|---|---|
| Crossing a word — several taps, or a hold | w b e — one tap |
| Crossing a URL — forty taps, or a hold you overshoot | W B E — one tap |
| Reaching the end of a long line — a hold | 0 ^ $ — one tap each |
| Reaching the top of the output — many page presses | gg G, or CtrlU CtrlD for half a page |
| Selecting a run of text — a careful drag | v and V, plus the text objects — viw, vip |
| Copying — a long-press and two handle drags | y — and it lands on the system clipboard too |
| Finding a word further up — scroll and squint | / and ?, and * # for the word already under the cursor |
| Putting the cursor mid-command — tap, miss, tap again | a motion lands exactly, and i starts typing there |
One row deserves a pause: * searches for the word already under the cursor. Finding every other mention of a long identifier costs two taps instead of typing it out on a soft keyboard — and not typing is the whole game on a phone.
The key row swaps to the Vim set
Above the soft keyboard sits Circuitry's key row, which pages sideways. While a terminal is in normal mode it replaces its ordinary control page with a Vim set, because most of the usual contents are dead weight there — tab and the modifiers do nothing, and the left and right arrows are exact duplicates of h and l, one tap away on the keyboard you are already looking at.
The Numbers page moves up to sit immediately behind the Vim set — ahead of every other page. A count is digits — 3j, 5W, 2yy — and a count is the cheapest way to repeat anything, so leaving the digits four swipes out would be the same as not having them.
Every page is a whole set, not a slice of a list. Each one is esc, five or six characters, ctrl, and the repeating up and down arrows.
esckeeps the first slot on every page. It is both the way out of normal mode and the way to send a real Esc, and it holds the same slot it has on the ordinary key row, so your thumb already knows where it is.ctrlis on every page too, because it is the modifier Vim actually uses — CtrlU CtrlD CtrlF CtrlB for the page scrolls — and a phone has no key for it.- The up and down arrows end every page. They look redundant beside
kandjand are not: these auto-repeat while you hold them, and a letter key does not. Scrolling any real distance through scrollback is a hold, not forty taps.
What is on each page to begin with
- First page —
/0$^?*— searching, and the ends of a line - One swipe —
{}"'and the backtick, then#— stepping between blocks of output, and the delimiters you need foryi"andci' - Two swipes —
()[]<>— the remaining brackets - Three —
%;,~
A pair is never split across a swipe. { and } sit together because they are the block motions you use in the same breath, and the bracket pairs stay together for the same reason — though with brackets you only ever need one of the two, since either half names the object (yi( and yi) are the same command).
That is the starting arrangement, not a fixed one.
The row learns what you press
After that, the keys you actually reach for move to the front page and the ones you never touch drift back a swipe. You do not have to do anything or set anything — it counts what you press. Someone reading agent output all day lives in / and *; someone editing long commands lives in $ and ^. The row ends up shaped like whichever of those you are.
Trying a key once will not shuffle the front page. The defaults carry real weight, so a challenger has to be genuinely and repeatedly used before it displaces one.
It carries only what the keyboard hides
Two rules keep the learning from making things worse.
No letters, in either case. h j k l w b y v i d are one tap on the layer already in front of you, and G W N I A are that same layer plus a shift — two taps, no layout change. A slot spent on any of them would buy almost nothing. Meanwhile the delimiters sit two layers deep, behind 123 and then #+=, and there is no backtick on an iOS keyboard anywhere at all. So the delimiters get those slots, and that is precisely what makes yi" and ci' and da( practical with a thumb. Digits stay for the same reason: 0 is not on the visible keyboard either.
It will not rearrange under your thumb. The order is worked out at the moment you enter normal mode and then held, so nothing moves mid-use. The page you were on before comes back when you return to typing.
The badge is always the way back
In normal mode a badge appears in the corner of the terminal showing NORMAL — or VISUAL LINE, or the search you are part-way through typing. Tapping it returns you to typing, whatever mode you are in. That is the escape hatch: you never have to work out which mode you are stuck in, and you never have to find a key to get out of it. i does the same, and starts you typing exactly where you were standing.
Errands that fit a thumb
| To do this on a phone | Press |
|---|---|
| Interrupt an agent mid-turn | Esc Esc |
| Copy a URL out of the output | Esc → move to it → yiW |
| Copy the block an agent just printed | Esc → move into it → yip |
| Lift a path out of a quoted error | Esc → onto the line → yi" |
| Find every mention of a word you can see | Esc → onto it → * → n |
| Get a line out of the bottom two rows | Esc → move to it → zz |
| Fix a word in what you are typing | Esc → b → ciw → type it |
| Clear the whole command | Esc → dd |
| Open a link | Esc → onto its line → gx |
| Get back to typing | i, or tap the badge |
Try it
Open a terminal on your phone and turn on Vim keys from the terminal's own menu — long-press, and it is the last item.
- Run something that prints a few screens of output, then press
escon the key row. The badge appears and the row swaps to the Vim set. - Swipe the row once to the right, and again, to see what is behind the first page. Swipe back.
- Press
ggto go to the top of the scrollback, then hold the down arrow on the row and watch it repeat. - Press
/, type a word you can see, press Enter, thenna couple of times. - Land on a line with a URL on it, press
Wuntil you are on it, thenyiW. It is now on your system clipboard too — paste it anywhere on the phone. - Press
pto put it into your prompt, thenito get back to typing. - Do the whole thing once more without looking at this page.
You now know: why a phone is where Vim pays off fastest — distance, not missing keys — what the key row holds in normal mode and why, and the two-press Esc ladder.
Related
- Vim Mode in Editors & Terminals — the full reference
- The phone key row — what the row holds the rest of the time
- CLI Coding Agents
- Terminals
← Lesson 6 — Terminals and CLI Coding Agents · Practice, Cheat Sheet and Where to Learn More →