⌨️ pi-vim-editor

Edit prompts by sentence and paragraph, reshape blocks, and reflow prose— without replacing your editor. pi-vim-editor adds Vim-style INSERT and NORMAL modes by decorating the installed editor. Editor-extension compatibility depends on load order; see Usage.

🚀 Installation

pi install npm:pi-vim-editor

✨ Usage

The prompt starts in INSERT mode. Press Esc for NORMAL mode, where the common Vim motions, operators, and text objects edit the prompt, and v, V, or Ctrl-V start Visual mode. Press Esc again in NORMAL mode to interrupt the agent, as usual. By default, the current mode shows in a corner of the editor border.

Usually, load pi-vim-editor after extensions that customize the editor. For framing extensions, order also affects Visual highlighting and H/M/L: these are disabled if the editor pi-vim-editor decorates has already rearranged Pi's rows. A framing extension can instead wrap the Vim-decorated editor and show the Vim status itself. See docs/integration.md.

⌨️ Key bindings

Counts work on motions and most edits, as in 3w, d3w, or 2dd. Keys Vim doesn't use, such as Enter, Tab, arrows, and Ctrl or Alt shortcuts, keep doing what they do in Pi. The exceptions in NORMAL mode are Ctrl-V, which starts Visual block mode instead of pasting an image, Ctrl-R, which redoes, and Ctrl-]. While a search query is open, its keys stay with search instead of Pi (see Literal prompt search).

Modes and Esc

After you submit a prompt, the editor is back in INSERT mode.

Motions

Use 2} to move forward two paragraph boundaries or d} to delete up to the next boundary. Only empty lines separate paragraphs for these motions; space/tab-only lines do not. Consecutive empty lines form one separator run. These motions do not recognize Markdown, nroff macros, or section markers.

Literal prompt search

In NORMAL or Visual mode, type /text and press Enter to search forward, or ?text to search backward. Search is literal and case-sensitive, not Vim or JavaScript regex: .*, brackets, and backslashes match themselves. It searches only the prompt, never the transcript or pasted-block contents or markers. Matches respect grapheme boundaries.

Use n to repeat in the accepted direction and N in reverse; N doesn't change the direction of later n. Counts work (2/text, 3n). Search wraps with a notice. Enter on an empty query reuses the last accepted text in the chosen / or ? direction. No match leaves the cursor in place with a notice.

The border shows the query unless indicator is none. Backspace deletes its last grapheme; Esc or Ctrl-[ cancels without moving. Enter confirms, never submits. Paste adds to the query, including line breaks; other shortcuts and navigation keys are ignored until you confirm or cancel. External cursor or text changes cancel the query. Search memory is private to each editor and resets after submit.

Operator search (d/text, cn, and similar) isn't supported: it cancels without editing. Instead, use v/text, Enter, then d, c, or y to act on the inclusive selection. There is no regex, query history UI, or live preview.

Operators and text objects

d deletes, c changes, y yanks, gu lowercases, and gU uppercases. gq and gw reflow prose into hard-wrapped lines. Combine them with a motion (dw, c$, y3j, d%, d), d}), double them for whole lines (dd, cc, yy, guu, gUU), or use a text object:

Sentence objects can span lines: cis changes the whole current sentence, even from its middle, and das also takes adjacent separator whitespace. Use d2as for two sentences. Quote and bracket objects stay on the current line. With the cursor inside `src/old.ts`, type ci` to replace the path while keeping the backticks.

Use cip to rewrite an instruction paragraph, dap to delete it with adjacent blank lines, or yip to copy its whole lines. Empty and space/tab-only lines separate paragraphs. ap prefers trailing blank lines, falling back to leading ones at the prompt’s end; d2ap deletes two paragraphs. These are prose objects, not Markdown heading, list, or fence objects.

Manual prose reflow

Use gwap to wrap the current paragraph and keep your place in the text, or gqap to wrap it and move to its end. Both retain blank paragraph separators; gwip and gqip leave those separators outside the formatting range. gqq and gww format the current line; 3gqq and 3gwgw format three lines. You can also use motions (gq}, gwj) or format a Visual selection with gq or gw. Formatting always covers whole touched lines, preserves the register, and supports one-step u and . repeat.

The default width is a fixed 79 display columns, configurable with vimEditor.textWidth. Wrapping keeps the first line’s indentation, leaves long words intact, and refuses ranges containing pasted blocks. It only runs when requested: there is no automatic formatting while typing and no Markdown, comment, or filetype parsing.

Edits, undo, and repeat

Deletes, changes, and yanks share one register. Yanks also go to the system clipboard. Prefix a command with "+ or "* to use the system clipboard explicitly: "+dd cuts a line to it, and "+p puts it. Edits that would cut into a pasted block ([paste #1 +24 lines]) are refused.

Visual modes

Motions and text objects (viw, vi(, vis, v2as, vip, v2ap) extend the selection. vip and vap start whole-line paragraph selections.

Quitting Pi

The full spec, including where it differs from Vim, is in docs/ux.md.

🆚 Comparison

How pi-vim-editor compares with other Vim extensions for Pi, based on their documented features. This table describes current main; the published npm release may not yet include its latest features.

¹ Requires Pi's hardware cursor and a terminal that supports cursor shapes.

⚙️ Configuration

Set the manual prose wrapping width in Pi’s settings.json:

{ "vimEditor": { "textWidth": 72 } }

textWidth accepts a positive integer in display columns. Missing or invalid values (including 0) use 79, regardless of terminal or editor width. This is a fixed default, not Vim’s window-dependent textwidth=0 fallback.

To make plain p paste the system clipboard, and every delete and change copy to it, as with Vim's clipboard=unnamedplus:

{ "vimEditor": { "clipboard": "unnamedplus" } }

Move the mode label to another corner in Pi's settings.json:

{ "vimEditor": { "indicator": "top-left" } }

Choose bottom-right (default), bottom-left, top-right, top-left, or none. To hide the label entirely:

{ "vimEditor": { "indicator": "none" } }

With none, mode text, pending commands, and search queries are visible only if another extension renders them from the status capability. Vim editing, Visual highlighting, and optional cursor shapes remain active. Settings are read when a session starts, including for an existing editor.

To also show the mode through the cursor shape, enable both settings:

{
  "showHardwareCursor": true,
  "vimEditor": { "cursorShape": true }
}

cursorShape defaults to false. When enabled, INSERT uses a steady bar, NORMAL and Visual modes a steady block, and REPLACE a steady underline. Pi still controls cursor visibility; with its hardware cursor hidden, the software cursor stays unchanged.

To pick the style per mode, set cursorShape to a map instead of true:

{
  "showHardwareCursor": true,
  "vimEditor": {
    "cursorShape": {
      "insert": "blinking-bar",
      "normal": "blinking-block",
      "replace": "blinking-underline"
    }
  }
}

The keys are insert, normal, visual (all Visual modes), and replace. The styles are steady-bar, blinking-bar, steady-block, blinking-block, steady-underline, blinking-underline, and reset for the terminal's default. Missing or invalid entries keep their default style. Pi merges maps across global and project settings, so a project map only overrides the entries it names; {} doesn't reset inherited entries. Set cursorShape to false to turn off a map inherited from your global settings.

Cursor shapes require DECSCUSR support in your terminal and, if used, tmux or another multiplexer. Disable cursorShape if your terminal ignores the sequences. The extension resets the shape with DECSCUSR 0, the terminal's default (a blinking block in xterm), when the prompt loses focus, Pi opens an external editor or suspends, or the extension shuts down or reloads. It does not query or restore your pre-Pi cursor shape.