vfv-0.1.0 is not a library.

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.

https://github.com/user-attachments/assets/e3ec4515-ac0d-453f-851f-ca449b19e877

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 vive-file-viewer

Or build from source:

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

Usage

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

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

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

Configuration

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"

License

MIT

vfv 0.1.0