pi-vim-tree

Vim-style folding, motion, jump list and marks for Pi's built-in /tree view.

Packages

Package details

extension

Install pi-vim-tree from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-vim-tree
Package
pi-vim-tree
Version
0.1.2
Published
Nov 20, 2026
Downloads
511/mo · 511/wk
Author
ooostrich
License
MIT
Types
extension
Size
129.5 KB
Dependencies
0 dependencies · 2 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-vim-tree

Vim folding, motion, jump list, marks and a Markdown preview for Pi's built-in /tree.

It patches the native tree in place - same rows, same search, same actions - and puts Vim keys on top. Nothing is replaced, and /vim-tree off restores native behaviour exactly.

Two panels: Pi's default tree list, and a preview of the selected message.

Everyday Keys

The list panel is Pi's own /tree - every kind of entry appears there: user message, reply, tool call. The preview panel is added by this extension and shows the full content of the row under the cursor, rendered as Markdown.

I want to Tree panel (left) - Pi's /tree list Preview panel (right) - the selected message
Move j / k - or the wheel ctrl+e / ctrl+y line · ctrl+u / ctrl+d half page · ctrl+f / ctrl+b page - or the wheel
Switch branch h / l (previous / next branch head, wraps) · also ctrl+j / ctrl+k, shift+up / shift+down -
Jump by number {n}G row n · G last · gg first · % matching branch · g0 my branch -
Come back ctrl+o / ctrl+i - the jump list, Vim's -
Park a spot m + a letter, back with ` + the same letter -
Label a row L edit its label · T show / hide label timestamps -
Wipe bookkeeping J clears the jump list · M clears all marks -
Fold noise away za toggle · zc / zo close / open · zM / zR all · zv reveal the cursor row -
Thin the tree out gt / gl / gu / ga / gd filters (remembered) -
Find something / then n / N (or p) -
Leave q, or your app.session.tree key -

Learn h / l first: branch heads are the only structure a tree has, so hopping them does what w / b does in text - and every hop lands in the jump list, so ctrl+o walks you back through the branches you visited.

Contents

Install · Requirements · Commands · Keys · Behaviour · Compatibility · Troubleshooting · Differences from Vim · Releasing · Development

Install

pi install npm:pi-vim-tree

One-off run, or without npm at all:

pi -e npm:pi-vim-tree
mkdir -p ~/.pi/agent/extensions && cp extensions/vim-tree.ts ~/.pi/agent/extensions/

/reload hot-reloads; files in ~/.pi/agent/extensions/ are auto-discovered. PI_VIM_TREE=0 loads the extension but applies nothing.

Requirements

Pi 1.5.1+, Node 22.19+. The patch targets Pi's internal tree classes inside the compiled bundle. Chunk names change every release (chunk-44DLKSKE.js in 1.5.0, chunk-ZKNSXGL5.js in 1.5.1), so the chunk is found by content, not by file name. If the internals change shape, nothing is patched, the native tree keeps working, and /vim-tree reports why. No runtime dependencies.

Commands

Command Effect
/vim-tree State, build id, and the reason if the patch could not be applied
/vim-tree on Apply the patch
/vim-tree off Undo every patch

off is a full undo: patched methods are reverted in reverse order, and the tree instance gets its original height, filter mode, fold state and label-timestamp flag back. While the label editor is open the extension steps aside and hands every key to Pi.

Keys

Native keys (j / k, enter, /, L, T) keep working. Lowercase l is branch motion and t is unbound, which is why label and label time live on the uppercase keys.

Folding

Key Action
zc Close the fold under the cursor
zo Open the fold under the cursor
za Toggle the fold under the cursor
zC Close the fold and the whole subtree
zO Open the fold and the whole subtree
zA Toggle recursively - open the entire subtree, or close every fold in it
zm Fold one level deeper
zr Unfold one level
zM Close all folds
zR Open all folds
zj / zk Jump to the next / previous fold
zv Open just enough folds to reveal the row that was folded away

Motion

Key Action
h / l Previous / next branch head (wraps)
ctrl+j / shift+down Next branch head (wraps)
ctrl+k / shift+up Previous branch head (wraps)
g0 Jump to the current session branch
gg Jump to the first row
G / {n}G Jump to the last row / to row {n}
% Jump to the matching branch
gt / gl / gu / ga / gd Filter: no tools / labelled only / user only / all / default
f / b Page down / up
u / d Half page up / down

List paging is the lowercase f / b / u / d group; ctrl+f / ctrl+b / ctrl+u / ctrl+d belong to the preview.

Preview

Key Action
ctrl+h (or F4) Toggle the side preview
ctrl+e / ctrl+y Scroll the preview by one line
ctrl+u / ctrl+d Scroll the preview by half a page
ctrl+f / ctrl+b Scroll the preview by a whole page

The body is rendered with Pi's own Markdown component and getMarkdownTheme(), so headings, lists, quotes and code blocks look like the conversation, syntax highlighting included. It borrows the active theme; without one it falls back to plain wrapped text.

Those four control keys belong to the preview and nothing else. Closed, too narrow, or a body that fits on one screen - they do nothing: no fallback to the list, no leak to Pi's native keys.

Mouse

Only the wheel is taken over: over the preview panel it scrolls the preview by lines, over the tree panel it moves the cursor row by row (like repeated j / k, never a screen jump). Over the preview panel it falls back to the tree when the preview cannot scroll. Clicks and drags are Pi's; the label editor keeps every event.

Search

Key Action
/ Native search box (incremental, backspace works)
n / N Next / previous match
p Previous match
ctrl+l Clear the search term and the highlight

Leaving

Key Action
q Close the tree (like q in a Vim help window, or in less / fzf)
your app.session.tree key Close the tree - the key that opened it closes it, so the binding toggles

The toggle key is whatever keybindings.json binds app.session.tree to, read through Pi's KeybindingsManager - not hardcoded. It is unbound by default, so nothing happens until you bind it:

{ "app.session.tree": ["ctrl+shift+t"] }

On terminals where ctrl+i and Tab are the same byte, binding it to ctrl+i makes Tab close the tree too. esc keeps its native meaning (cancel the search box, otherwise leave the tree).

Filters

The mode you pick with gt / gl / gu / ga / gd is remembered: in memory for the session, and in vim-tree.json in the agent directory (~/.pi/agent/vim-tree.json unless PI_CODING_AGENT_DIR says otherwise) across launches. Pi passes treeFilterMode in when the tree opens and never writes back a mode picked inside, so the extension records it.

Changing treeFilterMode in /settings wins - that value becomes the new baseline and the memory is resynced to it, so the setting is never shadowed. Deleting vim-tree.json resets the memory to the setting.

Behaviour

Folds

Pi marks foldable rows with ⊟, ⊞ once closed. pi-vim-tree folds exactly those rows and nothing else.

  • Only branch points fold - leaf rows and the root have no marker.
  • A fold closes the whole subtree below it.
  • zm / zr step levels, numbered consecutively like Vim's foldlevel (Pi's indent only increments at branch points, which would give 1 -> 3 -> 5). The current level and the total live in the title bar: Session Tree Fold 2/5.

Line Numbers

Numbers are computed against the unfolded list, the way Vim counts buffer lines. Folding hides rows and leaves their numbers blank; nothing below is renumbered.

So every jump resolves against one fixed list: G, {n}G, gg, %, g0. If the target sits inside a fold, the fold opens first and the jump lands on the row itself.

Cursor Row

One logical cursor row is kept - the row the cursor really belongs to, even while hidden.

  • Folding does not move it; while hidden, the cursor is drawn on its nearest visible ancestor.
  • Opening the fold puts the cursor back on it. Only moving the cursor replaces it.
  • The number of folds covering it comes from the parent chain, so folds in unrelated branches are never counted.

zv separately remembers the row a fold hid, and moving the cursor does not clear that memory - unlike the logical cursor row, which follows the cursor by Vim's rules.

Marks

m plus a name stores the current row; backtick plus the same name jumps back, opening folds if needed.

Key Action
m + letter or digit Set a mark on the current row
` + letter or digit Jump to that mark
` + ` Jump to the position before the last jump - press again to come back, and again to go back
M Delete all marks (Vim's :delmarks!)

62 names: a-z, A-Z, 0-9. No single-mark delete - d is half-page scroll, so a mark is cleared with M or overwritten.

Marks live in the extension, so they survive closing and reopening /tree, and are cleared when the session changes - the row ids belong to the old session.

Jump List

Key Action
ctrl+o / ctrl+i Older / newer position in the jump list
J Clear the jump list (Vim's :clearjumps)

Only jumps are recorded: gg, G, {n}G, %, g0, branch-head jumps (h / l, ctrl+j / ctrl+k, shift+down / shift+up), mark jumps, a committed search, n / N / p. Movement (j / k), list paging (u / d, f / b), fold jumps (zj / zk) and preview scrolling do not enter the list.

Like browser history, a new jump truncates what was ahead. A count works: {n} then ctrl+o. Entries are deduplicated by row, so scanning l / h never piles up the same branch twice. Vim's limits apply: at most 100 entries, no duplicates.

Status Bar

showcmd in three tiers:

State Behaviour
Waiting for a second key (11, g, z) The prefix stays on screen
Command finished (j, 11G) The command flashes briefly, then clears
Unmatched key Nothing is shown

The mode badge (NORMAL / SEARCH) is followed by the pending input. Counters appear only when there is something to report:

Session Tree  Fold 2/5  ·  Match 1/3  ·  Jump 4/9  ·  Mark a,b

Jump x/y is your position in the jump list and its length; Mark a,b lists the marks you set. J and M clear them, and the counters go with them.

Layout

The list keeps a fixed height - 60% of the available space, capped at 30 rows - so folding, filtering or a shorter session never resizes the panel. The preview panel takes the right 55% of the width, fzf --preview-window right:55% style, so toggling it causes no reflow at all.

Compatibility

The patch rides on private tree classes in Pi's compiled bundle, so it self-checks on startup. When the internals change shape it stays silent, leaves the native tree alone, and /vim-tree says why. Chunks are located by content, so renamed files (chunk-44DLKSKE.js -> chunk-ZKNSXGL5.js) are fine.

Troubleshooting

/vim-tree says "not applied". The internals changed in a way the extension does not recognise. Update Pi and reload; the reason is printed either way.

The keys do nothing. The extension is off (/vim-tree on), or the tree does not have focus. Native keys work in both cases.

The tree looks shorter than before. Fixed height - 60% of the terminal, 30 rows max. Resize the terminal.

ctrl+f does nothing. The preview is closed, too narrow, or its body fits on one screen - those four keys only scroll the preview. Page the list with f / b or u / d.

The tree opens with a filter I did not pick. That is the remembered mode. Change treeFilterMode in /settings (it wins and resyncs), or delete vim-tree.json from the agent directory.

The tree shows a lot of remote-pi rows. Those are custom messages the remote-pi package appends on every rename. Pi's filter has no way to hide custom messages.

The slash command shows up as /vim-tree:1 and /vim-tree:2. Two copies are loaded - Pi appends :1 / :2 when a command name is registered twice, and the [u] / [p] / [t] tag tells you the scope. The copy that loaded last owns the patch, so /vim-tree off on the other one only disables itself. Keep one source: pi list, pi remove <source>, ~/.pi/agent/extensions/, the extensions key in settings. /vim-tree warns when it detects another copy.

The preview shows raw Markdown. The theme was unavailable at render time, so it fell back to plain text. Restarting Pi re-initialises the theme; if it still happens, /vim-tree and the Pi log say why.

Differences from Vim

Deliberate:

Behaviour Vim pi-vim-tree
g0 Go to column 0 Jumps to the session's active branch - a tree has no columns
zm / zr Reset manually closed folds Manual folds survive
zm Decrements a counter, so closing several levels takes several presses Steps one level immediately
Folding the root Not possible Falls back to folding the root when a chain has no branch point
Search scope Whole buffer, including hidden lines Visible rows only
zX / zE Operate on manually closed folds Not implemented - the tree has a single kind of fold
Mark names a-z, A-Z (digits are numbered buffers) The same 62 names, and m0-m9 set marks too
ctrl+f / ctrl+b Scroll the buffer a page Scroll the side preview; the list pages with f / b
ctrl+u / ctrl+d Scroll the buffer half a page Scroll the side preview; the list pages with u / d
Filter mode N/A Remembered across sessions in vim-tree.json

Releasing

npm publish --access public

Bump version in package.json and add a matching ## [x.y.z] heading to CHANGELOG.md first - Pi shows those entries to users after an update.

Publishing needs a second factor: use the authenticator app or the browser confirmation, not a recovery code (npm treats that as security-sensitive and can suspend the account). For unattended releases, configure trusted publishing (OIDC) on the package and point it at a GitHub Actions workflow.

Publishing from a directory without a git repository is fine: no gitHead, no provenance, no repository link on the npm page, and every release is a manual npm login plus 2FA. The TypeScript source ships in the tarball, so users can read exactly what runs.

Verify the artifact without installing it:

pi -e npm:pi-vim-tree

Development

The extension is a single file with no build step; npm is only needed to publish.

Pick one source to load it. Loading the same extension twice is what produces /vim-tree:1 / :2, and the copies then fight over the patch.

Goal Command Scope tag
One-off run pi -e ./extensions/vim-tree.ts [t]
Hot reload with /reload link or copy into ~/.pi/agent/extensions/ [u]
Keep the file where it is add the path to extensions in ~/.pi/agent/settings.json [u]
As a package pi install ./this-dir [u]

The tag is what Pi prints in autocomplete: u = user, p = project, t = temporary. A symlink keeps one copy of the file while /reload still sees edits:

ln -sfn "$PWD/extensions/vim-tree.ts" ~/.pi/agent/extensions/vim-tree.ts

npm install is never needed

Everything the extension imports comes from Pi; npm install has nothing to install and replaces the links test/setup.sh creates (re-run it afterwards). The links are per package inside a real node_modules/@earendil-works directory on purpose: an earlier version linked the whole scope at Pi's own node_modules, and a stray npm install then resolved the peers through that link and pruned Pi's packages as "extraneous", leaving Pi unable to start.

Tests

./test/setup.sh   # link Pi's node_modules so bare node can import pi-tui
npm test

The suite drives the real TreeSelectorComponent from the installed bundle with real key bytes, and asserts on visible rows, the selected row, the title-bar counters, fold markers, the jump list and the marks. It covers /vim-tree off (the tree must render byte for byte like one never patched) and loads two copies on purpose to check that a stale copy's off cannot tear down the active patch. Re-run setup.sh after upgrading Pi.