pi-files-widget-overlay

An in-terminal floating file browser, file viewer, and Git diff overlay for Pi.

Origin

This is an overlay-focused fork of tmustier/pi-extensions — files-widget.

Screenshots

Install

Install from npm with Pi's package manager:

pi install npm:pi-files-widget-overlay

For local development, add the repository directory to Pi's global settings file ($PI_CODING_AGENT_DIR/settings.json, defaulting to ~/.pi/agent/settings.json):

{
  "extensions": [
    "~/pi-files-widget-overlay"
  ]
}

Dependencies

• Pi >=0.84.4
• git for Git status and diff mode when available

The extension has no bat, glow, or delta runtime dependency. It uses Pi's theme-aware syntax highlighter and Markdown renderer.

Commands

| Command | Description | | --- | --- | | /readfiles | Open the browser at the current directory. | | /readfiles <path...> | Open the browser with one or more absolute, relative, or ~-prefixed roots. Quote paths containing spaces. |

For development:

npm install
npm test
npm run typecheck

Browser keybindings

| Key | Action | | --- | --- | | j / k or ↑ / ↓ | Move the selection. | | Enter | Open a file or expand/collapse a directory. | | h / l or ← / → | Collapse/expand a directory; l / → opens a selected file. | | PgUp / PgDn | Page through the tree in the single-column layout. | | p | Toggle the tree/preview split on wide terminals. | | Tab / Shift-Tab | Switch to the next / previous command-provided root when multiple distinct roots are provided. | | y | Copy the selected file or directory's absolute path. | | * | Pin/unpin the selected directory (or selected file's parent) for default /readfiles roots. | | c | Toggle changed-only view within the current search results. | | C | Toggle expanded changed view within the current search results. | | [ / ] | Previous/next changed file; when searching, stay within the current results. | | / | Search file names. | | @ | Search literal file content asynchronously. | | u | Re-root at the parent directory. | | . | Return to the command's starting directory. | | + / = and - / _ | Increase/decrease panel height. | | ? | Show/hide the complete browser help. | | q / Esc | Close the overlay. |

While either search is active, type to search and use ↑ / ↓ to move. Enter keeps the query and returns to the normal browser help; its header displays the query as /foo (Esc clears) or @foo (Esc clears). Esc cancels the active search; Backspace deletes input and cancels when the query is empty. After confirming a browser query, Esc clears the retained query before a second Esc closes the overlay. Press the active search key again to clear the query.

Viewer keybindings

| Key | Action | | --- | --- | | j / k or ↑ / ↓ | Move the line cursor. | | PgUp / PgDn or Ctrl-U / Ctrl-D | Scroll by half a page. | | g / G | Jump to the top/bottom; <count>G jumps to a logical line. | | d | Toggle Git diff for a changed tracked file. | | m / r | Toggle rendered/raw Markdown in the normal, non-diff view. | | w | Toggle word wrap. | | y | Copy the current file's absolute path. | | / | Enter search mode. | | n / N | Next/previous search match. | | v | Enter or leave line-selection mode. | | c | Comment on selected lines. | | C | Comment on the whole file while selecting. | | [ / ] | Previous/next changed file. | | + / = and - / _ | Increase/decrease panel height. | | ? | Show/hide the complete viewer help. | | q, Esc, or ← | Return to the browser when not searching, selecting, or editing a comment. |

In search mode, type to search and press Enter to keep the query; its header displays /foo (Esc clears) and the match position (including [0/0] when no line matches). Esc or ← exits active search; Backspace deletes input and exits only when the query is empty; pressing / again clears the query. With a kept query, Esc or ← clears that query; a subsequent Esc or ← returns to the browser.

In selection mode, j / k or ↑ / ↓, PgUp / PgDn, Ctrl-U / Ctrl-D, and g / G extend or reset the selection; Esc, ←, or v cancels it. c opens the line-comment editor and C opens the file-comment editor. In the comment editor, Enter or Shift+Enter adds a line, ← / → moves the cursor, Backspace deletes, Ctrl+Enter, Ctrl+D, or supported Alt+Enter sends the comment, and Esc cancels.

Configuration

Browse-position restoration is disabled by default. To restore the last selected file or browser directory for each single-root /readfiles command root in the same Pi session, add this namespace to Pi's global settings file ($PI_CODING_AGENT_DIR/settings.json, defaulting to ~/.pi/agent/settings.json):

{
  "piFilesWidgetOverlay": {
    "restoreBrowsePosition": true
  }
}

The extension reads restoreBrowsePosition but never writes it. Pinning or unpinning with * updates only piFilesWidgetOverlay.pinnedRoots, preserving other settings fields. Each single-root command root keeps an independent memory-only browsing position: /readfiles and equivalent resolved paths restore their own last position. An explicit single /readfiles <path> starts at that path. Accessible pinned roots are appended to every command's root list after explicit paths (with normalized-path de-duplication), while multi-root state is never saved on close. Equivalent path spellings share a normalized absolute-path record.

Multi-root commands

Pass roots directly to the command, separated by whitespace; quote paths containing spaces:

/readfiles ./src ./test
/readfiles "./my src" "./my test"

The first path must be accessible and is the initial root. Press Tab or Shift-Tab to switch roots. Selecting an inaccessible secondary path reports it as unavailable. Multi-root root selection and locations exist only while the Overlay is open; a valid existing browse record for the first root may initialize that root, but multi-root state is never saved on close.

Notes and edge cases

• The overlay is centered at 95% of terminal width with a one-cell margin. Its maximum height is 95% of the terminal; panels start at 85% and + / - adjust within that limit.
• Wide terminals use a read-only 3:7 tree/preview split. The preview follows the selected item; g / G, <count>G, PgUp / PgDn, Ctrl-U / Ctrl-D, and w control it without enabling edits.
• Hidden project files such as .pi/ and .github/ remain visible. .git/ and common dependency/build caches remain hidden.
• Directory symlinks show ↗ and can be expanded. Untracked files show [UNTRACKED] and open in normal view.
• Searching or selecting rendered Markdown switches it to raw source so matches, line numbers, and comments stay aligned. On terminal-width changes, rendered Markdown keeps the current paragraph when it can identify it; otherwise it returns to the top.
• Comments for files outside the current project use absolute paths; comments for project files use project-relative paths.
• Image, binary, and terminal-control-character files show a safe metadata placeholder instead of rendering their bytes. File names, paths, and error messages are sanitized before terminal rendering.
• Line counts load asynchronously. The Files title reports scan activity and short-lived scan errors. Large non-Git folders can load progressively and show [partial] in safe mode.
• Git status refreshes every 3 seconds while the overlay is open. Folder line counts appear only while the folder is collapsed.

License

MIT