pi-vim-tree
Vim-style folding, motion, jump list and marks for Pi's built-in /tree view.
Package details
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/zrstep levels, numbered consecutively like Vim'sfoldlevel(Pi's indent only increments at branch points, which would give1 -> 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.