pi-vimotion

pi-vim

Modal vim editing for pi's prompt box.

Two modes, operators that compose with motions and text objects, find/till, and buffer jumps. Vim mode is off by default — toggle it with /vim.

Press K in normal mode to see the full keybinding reference.

https://github.com/k3-2o/pi-vimotion

Install

Manual (clone into extensions)

git clone https://github.com/k3-2o/pi-vimotion.git ~/.pi/agent/extensions/pi-vim

Then /reload in pi.

Via pi package manager

pi install pi-vimotion

(Requires the package to be published — coming soon.)

Quick Start

What	How
Turn vim on/off	/vim (persists across sessions)
Enter normal mode	escape
Enter insert mode	i / a / I / A / o / O
Show keybindings	K in normal mode
Undo	u
Abort streaming	double-tap escape from insert

Design

pi-vim is deliberately minimal. It mirrors the vim model used in OpenAI Codex's composer: two modes (Normal + Insert), no visual mode, no dot-repeat, no registers. Selection-style editing is handled by operators + text objects instead.

The implementation layers on top of pi's built-in editor wherever possible — many motions and single-stroke edits delegate to pi's own commands. Only the genuinely vim-specific parts (operators composing with motions, text objects, find/till, the yank register) are custom.

Features

Motions

Keys	Action
h j k l	Left / Down / Up / Right
w b e	Word forward / backward / word end
0 $	Line start / line end
f F	Find next / previous char (f( → next paren)
t T	Till before next / after previous char
; ,	Repeat last find / repeat reversed
gg G	First line / last line

Operators

Keys	Action
d + motion	Delete (e.g. dw, d$, df,)
y + motion	Yank (e.g. yw, y$)
c + motion	Change — delete + insert (e.g. cw)
dd yy cc	Delete / yank / change whole line
dj dk	Delete current + next / previous line (linewise)
dG dgg	Delete to end / start of buffer (linewise)
D C Y	Delete / change / yank to end of line
p	Paste after cursor (linewise or charwise depending on yank)

Text Objects

The power feature. After d / y / c, type i (inner) or a (around) then a target:

Keys	Action
iw aw	Inner word / a word (with trailing space)
i( a(	Inside / around parentheses
i[ a[	Inside / around brackets
i{ a{	Inside / around braces
i" a"	Inside / around double quotes
i' a'	Inside / around single quotes
i` a`	Inside / around backticks

Examples: di( deletes the contents of a function call, ci" changes a quoted string, da{ deletes a brace block and the braces.

Single-Stroke Edits

Keys	Action
x	Delete char under cursor
s	Delete char, enter insert
D C Y	Delete / change / yank to end of line
p	Paste after cursor
u	Undo

Insert Mode

All standard pi keybindings work in insert mode (ctrl+w delete word, ctrl+k kill line, ctrl+y paste, etc.).

Keys	Action
i a	Insert before / after cursor
I A	Insert at first non-blank / append at line end
o O	Open new line below / above
escape	Back to normal mode

Other

Keys	Action
K	Show keybinding reference overlay
escape	Cancel pending operator / leave insert
double escape	Abort streaming (from insert mode)

Status Indicator

Pi-vim shows the current mode in the footer:

Mode	Indicator
Normal	Vim: Normal (accent)
Insert	Vim: Insert (success)

What's Not Included (and why)

• Visual mode — replaced by operators + text objects; avoids custom rendering that conflicted with pi's line layout.
• Count prefixes (3w, d2w) — rarely useful in a prompt-sized buffer.
• Dot-repeat (.) — high complexity for a feature that earns its keep in long source files, not input boxes.
• Registers / named registers — pi's built-in kill ring covers the common paste cases.
• Redo (ctrl+r) — pi's base editor has no redo primitive.

Files

pi-vim/
├── index.ts            — Extension entry: /vim command, persistence, wiring
├── README.md
├── package.json
└── src/
    ├── editor.ts       — PiVimEditor: modes, key dispatch, operator state machine
    ├── keybindings.ts  — Keybinding reference + markdown overlay component
    ├── motions.ts      — Char classification + word-end helper
    ├── ops.ts          — Text operations: delete/yank/paste, text object ranges
    └── types.ts        — Shared types (VimMode, VimOperator, VimPending, ...)

License

MIT