pi-vim

Modal vim-like editing for Pi's input prompt. Covers the high-frequency 90% command surface.

install

pi install npm:pi-vim

Restart Pi after install.

configure

Settings are read from ~/.pi/agent/settings.json and project .pi/settings.json.

Default-equivalent settings.json:

{
  "piVim": {
    "clipboardMirror": "all",
    "modeColors": {
      "insert": "borderMuted",
      "normal": "borderAccent",
      "ex": "warning"
    },
    "syncBorderColorWithMode": false
  }
}

All keys are optional; omitting piVim is equivalent. Project overrides global; project modeColors replaces global modeColors, with missing modes defaulting above.

clipboardMirror: all mirrors unnamed writes; yank mirrors yanks; never keeps writes internal. Non-mirrored writes stay local for p / P.

syncBorderColorWithMode: false keeps Pi thinking border; true follows mode colors.

mode colors

piVim.modeColors accepts Pi theme foreground tokens. Missing, invalid, or unknown tokens use defaults above.

Usual/safest: accent, border, borderAccent, borderMuted, success, error, warning, muted, dim, text, thinkingText.

wrapping pi-vim

Supported: pi-vim first, @jordyvd/pi-image-attachments second. pi-vim does not wrap previous editors; wrappers decorate in place or forward the CustomEditor surface: lifecycle (handleInput, render, invalidate), text (getText, setText, insertTextAtCursor, getExpandedText), callbacks, actionHandlers, flags, reads (getLines, getCursor, getMode()). Inverse order, insert delegates, and generic composition are unsupported.

Smoke:

pi -e ./index.ts -e ../pi-image-attachments/index.ts
pi -e ./index.ts -e ../../../pi-image-attachments/index.ts

Check: insert text; add/paste image path; see [Image #1]; submit text+image stripped; switch INSERT/NORMAL.

contributor setup

Hooks install with npm install after cloning. To wire them explicitly:

npm run hooks:install

stats

• 192 commands: motions, operators, counts, text objects, undo/redo, ex quit
• sub-µs word motions via precomputed boundary cache (~4ms startup, ~150KB memory)
• 0 dependencies

30-second quickstart

Try on multi-line input:

Esc        # NORMAL mode
3gg        # jump to absolute line 3
2dw        # delete two words
u          # undo
<C-r>      # redo last undone edit (safe no-op when empty)
2}         # jump two paragraphs forward

Mode indicator (INSERT / NORMAL / EX) appears bottom-right, theme-colored and configurable.

Requires @mariozechner/pi-tui >= 0.47.0. With pi-tui >= 0.49.3 and DECSCUSR support, cursor shape follows mode; otherwise software cursor remains.

why pi-vim

• Fast modal editing without leaving Pi.
• Count-aware motions/operators (2dw, 3G, d2j, 2}).
• REPL-focused defaults; out-of-scope boundaries documented.
• Clipboard/register behavior is explicit and tested.

Use pi-vim for Vim muscle-memory in Pi prompts. Skip it if you need full Vim parity (visual mode, macros, search, extended ex-commands, …).

common recipes

| goal | keys | |---|---| | Jump to exact line 25 | 25gg (or 25G) | | Delete two words | 2dw | | Change current whitespace-delimited WORD | ciW | | Delete WORD plus adjacent whitespace | daW | | Change inside double quotes | ci" | | Delete inside parentheses | di( | | Yank braces with contents | ya{ | | Change to end of line | C | | Delete current + 2 lines below | d2j | | Yank 3 lines | 3yy | | Join 3 lines with spacing | 3J | | Jump 2 paragraphs forward | 2} | | Undo last edit | u | | Redo last undone edit | <C-r> |

full reference

mode switching

| key | action | |---|---| | Esc / Ctrl+[ | Insert → Normal mode | | Esc / Ctrl+[ | Normal mode → pass to Pi (aborts the agent under default Pi keybindings) | | : | Normal → EX mini-mode | | i | Normal → Insert at cursor | | a | Normal → Insert after cursor | | I | Normal → Insert at first non-whitespace | | A | Normal → Insert at line end | | o | Normal → open line below + Insert | | O | Normal → open line above + Insert |

Optional: move Pi's app.interrupt off bare escape in ~/.pi/agent/keybindings.json if it overlaps with Insert→Normal; user config wins.

ex mini-mode

Quit-only ex flows.

| key / command | action | |---------------|--------| | : | Enter EX mini-mode | | Enter | Execute pending ex command | | Esc | Cancel EX mini-mode | | Backspace / Ctrl+h | Delete one ex-command character; on bare : exits EX mode | | :q | Quit the current Pi session only when the prompt is empty or whitespace-only; otherwise show a warning | | :q! | Force quit the current Pi session even when the prompt has text | | :qa | Same safe quit policy as :q | | :qa! | Same force quit policy as :q! | | unsupported :{cmd} | Show warning notification; no quit |

Insert-mode shortcuts (stay in Insert mode):

| key | action | |---|---| | Shift+Alt+A | Go to end of line | | Shift+Alt+I | Go to start of line | | Alt+o | Open line below | | Alt+Shift+O | Open line above |

navigation (normal mode)

Most navigation keys accept a {count} prefix (max: 9999); % intentionally does not.

| key | action | |---|---| | h / l / j / k; {count}h/l/j/k | Move left/right/down/up; line moves clamp to the buffer | | 0 / ^ / _ / $ | Line start / first non-whitespace / counted first non-whitespace / line end | | gg / G; {count}gg / {count}G | Buffer start/end or absolute 1-indexed line | | w / b / e; {count}w/b/e | word start/back/end motions | | W / B / E; {count}W/B/E | whitespace-delimited WORD motions | | { / }; {count}{ / {count}} | Previous/next paragraph start | | % | Jump to the matching (), [], or {} partner |

word splits punctuation from keyword chars; WORD treats any non-whitespace run as one token (foo-bar, path/to). Paragraph starts are non-blank lines at BOF or after blank lines (^\s*$). { / } are navigation-only; brace operator forms (d{, c}, y{, …) are out of scope.

% uses a delimiter under the cursor or scans forward on the current logical line. It matches (), [], {} buffer-wide with lexical, nested, same-delimiter, parser-unaware matching; quotes/comments and mixed delimiters are not special. Missing/unmatched sources no-op. Counts are unsupported: {count}% consumes the count and no-ops; counted d% / y% / c% cancel without writes.

character-find motions (normal mode)

A {count} prefix finds the Nth occurrence of {char} on the line.

| key | action | |---|---| | f{char} | Jump forward to char (inclusive) | | F{char} | Jump backward to char (inclusive) | | t{char} | Jump forward to one before char (exclusive) | | T{char} | Jump backward to one after char (exclusive) | | {count}f{char} | Jump to Nth occurrence of char forward | | ; | Repeat last f/F/t/T motion | | , | Repeat last motion in reverse direction |

Char-find motions compose with operators: df{char}, ct{char}, d{count}t{char}, etc.

edit operators (normal mode)

Register-writing edits write to the unnamed register. With the default clipboard mirror policy, they also mirror to the system clipboard best-effort (clipboard failure never breaks editing).

text objects

Text objects compose as d/c/y + i/a + object. i means inner; a means around.

| object | keys | range | |---|---|---| | word | iw / aw | Keyword word; aw includes spaces | | WORD | iW / aW | Line-local whitespace-delimited WORD; aW includes adjacent whitespace | | quotes | i" / a", i' / a', i</code> / <code>a | Smallest containing quote pair on the line | | parentheses | i( / a(; aliases i) / a), ib / ab | Smallest containing pair | | brackets | i[ / a[; aliases i] / a] | Smallest containing pair | | braces | i{ / a{; aliases i} / a}, iB / aB | Smallest containing pair |

Semantics:

• WORD objects are line-local and whitespace-delimited.
• Quote objects are line-local; odd-backslash escapes are ignored; a includes delimiters only, not surrounding whitespace.
• Bracket objects are buffer-aware, nested, lexical, and not parser-aware; brackets inside strings/comments still count.
• Empty inner delimiter objects no-op for delete/yank; change enters Insert at the inner start without writing the register.
• Delimited counts cancel (d2i", 2ci(, y2a{). Counted word/WORD text objects work for delete/change only; counted yank text objects cancel.

delete d{motion} / dd

A {count} or dual-count prefix ({pfx}d{op}{motion}) is supported for word, WORD, char-find, and linewise motions. Maximum total count: 9999.

| command | deletes | |---|---| | dw / de / db; dW / dE / dB | word/WORD motion ranges; {count} repeats | | d$ / d0 / d^ | To EOL / BOL / first non-whitespace | | d_ / dd; d{count}_ / {count}dd | Current or counted whole lines | | d{count}j / d{count}k / dG | Linewise down/up/to EOF | | df{c} / dt{c} / dF{c} / dT{c}; d{count}f{c} | Char-find ranges | | d% | Inclusive range through the matching pair target | | diw / daw; diW / daW | Inner/around word or WORD | | d{count}iw / d{count}iW; d{count}aw / d{count}aW | Counted word/WORD text objects | | di" / da" (', </code>) | Inside/around quotes | | di(/da(, di[/da[, di{/da{| Inside/around brackets; aliases), ], }, b, B` |

change c{motion} / cc

Same motion and count set as d. Deletes text then enters Insert mode.

| command | action | |---|---| | cw / ce / cb; cW / cE / cB | Change word/WORD motion ranges + Insert | | c{count}w/e/b; c{count}W/E/B | Change counted word/WORD motions + Insert | | ciw / caw; ciW / caW | Change word/WORD text objects + Insert | | c{count}iw / c{count}iW; c{count}aw / c{count}aW | Change counted word/WORD text objects + Insert | | ci" / ca" (', </code>) | Change inside/around quotes + Insert | | ci(/ca(, ci[/ca[, ci{/ca{| Change inside/around brackets + Insert | |cc/c_; c{count}_| Change current or counted whole lines + Insert | |c$/c0/c^| Delete to EOL / BOL / first non-whitespace + Insert | |c%| Change inclusive range through the matching pair target + Insert | | … | Alld` motions apply |

single-key edits

A {count} prefix is supported for x, p, P. Maximum: 9999.

| key | action | |---|---| | x | Delete char under cursor (no-op at/past EOL) | | {count}x | Delete {count} chars | | s | Delete char under cursor + Insert mode | | S | Delete line content + Insert mode | | D | Delete cursor to EOL (captures \n if at EOL with next line) | | C | Delete cursor to EOL + Insert mode | | r{char} | Replace char under cursor with {char} (stays in Normal) | | {count}r{char} | Replace next {count} chars with {char} |

yank y{motion} / yy

Same motion set as d. Writes to register, no text mutation.

| command | yanks | |---|---| | yy / Y; {count}yy / {count}Y | Whole line(s) + trailing \n | | y{count}j / y{count}k / yG; y_ / y{count}_ | Linewise ranges | | yw / ye / yb; yW / yE / yB | word/WORD motion ranges | | y$ / y0 / y^; yf{c} | EOL / BOL / first non-whitespace / char-find | | y% | Inclusive range through the matching pair target | | yiw / yaw; yiW / yaW | Inner/around word or WORD | | yi" / ya" (', </code>) | Inside/around quotes | | yi(/ya(, yi[/ya[, yi{/ya{| Inside/around brackets; aliases), ], }, b, B` |

Counted word/WORD yank motions and counted yank text objects (y2w, 2yw, y2W, 2yW, y2aw, 2yaw, y2aW, y2a{, …) are intentionally not implemented and cancel the pending operator. Linewise counted yank ({count}yy, y{count}j/k) is supported.

put / paste

| key | action | |---|---| | p | Put after cursor (char-wise) / new line below (line-wise) | | P | Put before cursor (char-wise) / new line above (line-wise) | | {count}p | Put {count} times after cursor | | {count}P | Put {count} times before cursor |

Put reads the OS clipboard first unless the last local register write was not mirrored. Paste text ending in \n is line-wise.

undo / redo

| key | action | |-----|--------| | u | Undo one change in normal mode | | {count}u | Undo up to {count} changes in normal mode; clamps at available history | | Ctrl+_ | Undo in normal mode (alias for u) | | <C-r> | Redo one undone change in normal mode; safe no-op when redo history is empty | | {count}<C-r> | Redo up to {count} undone changes in order; clamps at available history and consumes count state (no leak to the next command) |

register and clipboard policy

• piVim.clipboardMirror = "all" is the default: every unnamed-register write mirrors to the OS clipboard best-effort.
• piVim.clipboardMirror = "yank" mirrors yanks only; deletes and changes update only pi-vim's internal shadow.
• piVim.clipboardMirror = "never" disables write mirroring while keeping internal register writes synchronous.
• Rapid mirrored writes coalesce: only the latest pending value is guaranteed to be mirrored.
• p / P read the OS clipboard first when no local write was skipped by policy, falling back to the shadow on read failure/timeout.
• If policy skipped the last local write, p / P use the shadow so delete/yank → put works without touching the OS clipboard.
• While a mirror is in flight, p / P use the shadow so immediate yank/delete → put stays ordered.
• Pi owns the terminal clipboard backends; on Wayland external state may lag while the shadow stays authoritative for immediate puts.

known differences from full Vim

| area | this extension | full Vim | |---|---|---| | $ motion | Moves past the last char (readline Ctrl+E) | Moves to the last char | | w / e / b + W / E / B | Cross-line for both word and WORD motions | Cross-line | | 0 / $ operators | Exclusive of the anchor col | 0 is inclusive of col 0 | | Undo / redo | Delegates undo to readline; normal-mode <C-r> redo is supported | Full per-change undo tree | | Visual mode | Not implemented | v, V, <C-v> | | Text objects | iw / aw, iW / aW, quote objects, and paren/bracket/brace objects; delimited counts cancel | Full text-object set | | % matching | (), [], {} only; lexical same-delimiter matching with no counts, quote/angle matching, parser/matchit logic, mixed-delimiter validation, or Visual % yet | Also supports percentage jumps and broader matching | | Count prefix | Operators, motions, navigation, x, r, p, P; capped at MAX_COUNT=9999 | Full support | | Registers / macros / search | Not implemented | Supported | | Ex commands | Quit-only EX mini-mode (:q, :q!, :qa, :qa!) | Full ex command-line surface | | Multi-line operators | d/c/y with w/e/b, W/E/B, j/k, and G; not the full Vim motion matrix | Rich cross-line semantics |

out of scope

Explicitly deferred:

• Visual modes (v, V, block visual), including Visual %
• Tag text objects (it, at)
• Paragraph/sentence text objects (ip, ap, is, as)
• Angle bracket text objects (i<, a<) or angle-bracket % matching
• Visual-mode text-object selection
• Quote matching via %, parser-aware delimiter matching, matchit-style matching, and mixed-delimiter structural validation
• Delimited-object counts (d2i", 2ci(, y2a{)
• Named registers ("a, "b, …), macros (q{char}, @{char})
• Ex surface beyond quit (:s, :g, :w, :r, …)
• Search (/, ?, n, N), repeat (.)
• Replace mode (R) — only r{char} is supported
• Count prefix beyond currently supported motions, including {count}% percent-of-file jumps
• No insert-mode <C-r> expansion, no cross-session redo persistence
• No upstream pi-tui redo prerequisite
• Window / tab / buffer management, plugin ecosystem compatibility

architecture notes

• index.ts handles modal keys; motions.ts and text-objects.ts hold pure range logic; types.ts holds shared types/constants; test/ uses Node's runner.

Run checks with npm run check.