pi-file-browser

A TUI file browser extension for pi. Navigate directories, open files for editing, and switch workspace sessions — all from within pi.

Install

pi install npm:@almegal/pi-file-browser

Or from this repo:

pi install git:github.com/almegal/pi-file-browser

After install, run /reload in pi.

Features

🗂 File browsing

Navigate the filesystem from within pi with vim-style keys.

Key	Action
↑ ↓ / j k	Move selection
← / h / Backspace	Go to parent directory
→ / l	Enter selected directory
Enter on directory	Select directory for workspace switch
Enter on file	Open file in pi editor
Esc / q	Close browser

🔍 Type-to-filter search

Start typing to instantly filter the file list. Press / to enter search mode explicitly.

• Prefix matches appear before substring matches
• Directories always float to the top
• In search mode, j/k/h/l are treated as search characters, not navigation — use arrow keys to move selection

Key	Action
Printable char	Append to search query
↑ ↓	Move selection within results
→	Navigate into selected directory
Enter	Confirm selection and act on entry
Esc / ←	Cancel search, restore previous position
Backspace	Delete last char, or exit search if query is empty

. Toggle hidden files

Press . to show or hide dotfiles and dot-directories (.env, .git, .pi, etc.). When hidden files are visible, the status bar shows a [hidden] marker. The hints bar shows .=hidden when files are hidden and A=hidden when they are visible.

🎨 Smart file-type icons

Files and directories get context-aware emoji icons instead of generic 📄/📂:

Type	Icon	Examples
TypeScript	🟦	.ts, .tsx
JavaScript	🟢	.js, .jsx, .vue, .svelte
Python	🐍	.py
Ruby	💎	.rb
Go	🦋	.go
Rust	🧩	.rs
Java	☕	.java
Kotlin	💜	.kt
Swift	🦁	.swift
C / C++	⚙️	.c, .cpp, .h
C#	💡	.cs
PHP	🐘	.php
Web / Markup	🌐	.html, .htm
Styles	🎨	.css, .scss, .less
Config/Data	📦	.json, .yaml, .toml, .xml
Data	📊	.csv
Database	🗃	.sql
Documentation	📝	.md, .mdx, .rst, .adoc
Plain text	📄	.txt
Shell	💻	.sh, .bash, .zsh, .fish
Lock files	🔒	.lock
Source maps	🗺	.map
Images	🖼	.png, .jpg, .jpeg, .gif, .svg, .webp, .ico
Audio	🎵	.mp3, .wav, .flac
Video	🎬	.mp4, .mkv, .avi, .mov
Archives	🗜	.zip, .tar, .gz, .bz2, .7z, .rar
Fonts	🔡	.ttf, .otf, .woff, .woff2
Binaries	⚡	.exe, .dll, .so, .bin, .wasm
Special files	🔨	Makefile, Dockerfile, Vagrantfile
Environment	🔑	.env, .env.*
Ignore files	🚫	.gitignore, .dockerignore
Package config	📦	package.json, tsconfig.json
License	📜	LICENSE, LICENSE*
Readme	📖	README.md, README*
Git	🔀	.git/, .github/
Pi config	🔮	.pi/ directory
Agents config	🤖	.agents/ directory
IDE	💻	.vscode/, .idea/
Tests	✅	test/, tests/, __tests__/
Source	📂	src/
Dist	📤	dist/
Build	🔨	build/
Docs	📚	docs/, lib/
Public	🌐	public/
Assets	🎨	assets/
Config	⚙️	config/
Scripts	💻	scripts/
Vendor	💰	vendor/
Bin	⚡	bin/
node_modules	📦	node_modules/

60+ extension mappings + special filename and directory detection.

🎨 Pi theme integration

The browser respects the active pi theme — no hardcoded colors:

Element	Theme token
Directory names	accent
Selected item	selectedBg
Hints & dim text	dim
Status bar	accent
Border frame	border / borderAccent
Loading message	muted

Switch pi themes and the browser adapts automatically.

🔄 Directory selection & session switching

Pressing Enter on a directory shows a menu:

• 🆕 New session — create a new pi session with that directory as cwd
• 🔄 Resume session — switch to an existing session (shows date, name, message count, and first message preview)
• ↩ Back — return to the browser

Config discovery: the browser detects AGENTS.md, CLAUDE.md, .pi/, .agents/ in the target directory and shows what's available.

Key	Action
↑ ↓	Select option
Enter	Confirm selected option
Esc / ←	Return to browser

✏️ File editing

Pressing Enter on a file closes the browser and opens pi's built-in editor with the file contents. On save, changes are written back. On cancel, the browser reopens at the same directory.

🧭 Navigation history

When navigating into a directory with →/l and then going back with ←/h/Backspace, the selection is automatically restored to the directory you came from — no need to scroll back to find your place.

📏 Status bar details

The status bar shows the selected entry's type (DIR or FILE), name, and file size (e.g., 1.2KB). When hidden files are visible, a [hidden] marker appears.

📜 Scroll behavior

The entry list scrolls to keep the selected item centered in view, so you never lose context when moving through long directories.

---

Usage

Run /files in pi to open the browser.

Build

npm run build

Architecture

src/
├── index.ts                  # Entry point (Composition Root)
├── app/FileBrowserApp.ts     # Command registration, session logic
├── components/FileBrowserComponent.ts  # TUI rendering & input
├── handlers/NavigationInputHandler.ts   # Key → action mapping
├── interfaces/               # IFileSystemProvider, IInputHandler, IPanelModel
├── models/PanelModel.ts      # Panel state (navigation, selection, search, hidden toggle)
├── providers/FileSystemProvider.ts      # Node.js fs implementation
├── services/
│   ├── ConfigDiscovery.ts    # Detects AGENTS.md, .pi/, etc.
│   └── FileTypeIconProvider.ts  # Extension/directory → emoji icon mapping
└── types.ts                  # Domain types