vfv (Vive File Viewer)

日本語

The ultra-lightweight terminal file viewer for vibe coding.

When you're in the flow with AI pair programming, you just want to quickly browse and check files—no complex setup, no heavy features. Just open, search, view, and get back to coding.

vfv.mp4

Why vfv?

• Zero config fuzzy search - Built-in nucleo (same as Helix editor). No fzf setup needed.
• 3MB single binary - Install and run. That's it.
• Vim keybindings - Navigate like you're used to.
• Syntax highlighting - Preview code with colors.
• .gitignore aware - Powered by ripgrep's ignore crate.

Not for you if...

You need file management (copy, move, delete), image preview, or plugin ecosystem. Use yazi instead.

Install

cargo install vfv

Or download pre-built binary from Releases.

Build from source

git clone https://github.com/noumi0k/vive-file-viewer.git
cd vive-file-viewer
cargo install --path .

Setup

Run the setup command to configure everything automatically:

vfv init

This will:

• Create config file
• Install shell completions (zsh/bash/fish)
• Install man page
• Update your shell rc file

Supported shells: zsh, bash, fish

Use --force to overwrite existing files.

Config File

Location:

• macOS: ~/Library/Application Support/vive-file-viewer/config.toml
• Linux: ~/.config/vive-file-viewer/config.toml
• Windows: %APPDATA%\vive-file-viewer\config.toml

# Editor command
editor = "vim"
editor_args = []

# Show hidden files by default
show_hidden = false

# Maximum lines to preview
preview_max_lines = 1000

# Syntax highlighting theme
# Options: "base16-ocean.dark", "base16-eighties.dark",
#          "base16-mocha.dark", "Solarized (dark)", "Solarized (light)"
theme = "base16-ocean.dark"

Usage

vfv              # Browse current directory (TUI)
vfv ~/projects   # Browse specific directory (TUI)

Keybindings

Press ? to show help screen.

File Browser

Key	Action
j / ↓	Move down
k / ↑	Move up
Enter / l	Open file / Enter directory
h / Backspace	Go to parent directory
g	Go to top
G	Go to bottom
e	Open in editor
y	Copy path to clipboard
f + char	Jump to entry starting with char
;	Jump to next match
,	Jump to previous match
/	Search (with options)
.	Toggle hidden files
r	Reload
?	Show help
q	Quit

File Preview

Key	Action
j / ↓	Scroll down
k / ↑	Scroll up
Ctrl+d	Half page down
Ctrl+u	Half page up
Ctrl+f / PageDown	Page down
Ctrl+b / PageUp	Page up
g	Go to top
G	Go to bottom
e	Open in editor
h / q	Back to file browser

Search

Press / to open search. You can use options like CLI:

main.rs           # Fuzzy search
config -e         # Exact match
src/main -d       # Directories only, path matching
telemo -d -e      # Directories only + exact match
main -b ~/dev     # Search from specific base directory

Key	Action
(type)	Enter query and options
Enter	Execute search
Esc	Cancel

Search Results

Key	Action
j / k / Tab	Select result
Enter	Open selected
/	New search
Esc	Cancel

CLI Search

Search files directly from the command line. Designed to be called from AI assistants or shell scripts.

vfv find <query> [path]    # Fuzzy search files/directories

Options

Option	Description
-d, --dir	Search directories only
-e, --exact	Exact match (no fuzzy)
-n, --limit <N>	Maximum results (default: 20)
-1, --first	Output only the top result
-j, --json	Output as JSON
-c, --compact	Compact JSON (single line)
-t, --timeout <SEC>	Timeout in seconds (default: 0 = no limit)
-q, --quiet	No spinner (for scripts/AI)

Path Matching

When query contains /, it matches against the full path:

vfv find "src/main" ~/dev    # Matches paths containing "src/*/main*"
vfv find "main" ~/dev        # Matches filename only

Examples

# Basic search
vfv find "config" ~/dev

# Find a directory and cd into it
cd $(vfv find "project" ~/dev -d -1 -q)

# Path search: find "telemo" under any "dev" directory
vfv find "dev/telemo" ~ -d

# Exact match
vfv find "config" ~/dev -e

# AI-friendly: quiet, compact JSON, with timeout
vfv find "main" ~/dev -q -j -c -t 5

Exit Codes

Code	Meaning
0	Results found
1	No results
124	Timeout

License

MIT