FileView (fv)

Zero-config terminal file browser with automatic image preview

English | 日本語

Screenshot

Why fv?

Lightweight ◄───────────────────────► Feature-rich

   nnn    lf    fv    ranger    yazi
  3.4MB  12MB  8MB    28MB     38MB

• Zero config - Install and run. No setup required.
• Auto image preview - Detects Kitty/iTerm2/Sixel/Halfblocks automatically
• Fast - 2.3ms startup, 8MB memory (vs ranger 400ms/28MB)
• Batteries included - Git status, syntax highlighting, PDF preview
• Vim keybindings - Navigate with j/k/h/l

Quick Start

cargo install fileview
fv

3-Min AI Workflow (Recommended)

# 1) Set up Claude MCP integration once
fv init claude

# 2) Generate compact context for AI
fv --context-pack review --agent claude

# 3) Resume previous AI session context
fv --resume-ai-session

Useful docs:

• Claude Code Guide
• Competitive Scorecard (weekly)
• Release Policy

Features

Image Preview

FileView auto-detects your terminal:

Keybindings (Quick Reference)

Full keybinding list

Claude Code Integration

FileView is the only terminal file manager with native AI tooling support.

# Project context for AI
fv --context

# Output directory tree
fv --tree --depth 2 ./src

# Quick file selection
selected=$(fv --select-mode --multi)

# Copy in Claude-friendly format (Ctrl+Y in fileview)

Smart Selection

MCP Server

Use FileView as a Claude Code MCP server with Git integration:

{
  "mcpServers": {
    "fileview": {
      "command": "fv",
      "args": ["--mcp-server"]
    }
  }
}

MCP 2.0 Tools (21 tools):

Full MCP documentation

CLI Options

fv [OPTIONS] [PATH]

Options:
  -p, --pick          Pick mode: output selected path(s)
  -f, --format FMT    Output format: lines, null, json
  --stdin             Read paths from stdin
  --on-select CMD     Run command on selection
  --choosedir         Output directory on exit
  -a, --hidden        Show hidden files
  --no-icons          Disable Nerd Fonts icons

Claude Code:
  -t, --tree          Output directory tree to stdout
  --depth N           Limit tree depth
  --context           Output project context (AI-friendly)
  --context-pack P    Output context pack preset (minimal/review/debug/refactor/incident/onboarding)
  --context-format F  Context pack format: ai-md, jsonl
  --agent A           Agent profile: claude, codex, cursor
  --token-budget N    Context pack token budget
  --include-git-diff  Force include git diff summary in context pack
  --include-tests     Include inferred test files in context pack
  --context-depth N   Fallback file scan depth for context pack
  --with-content      Include file contents in output
  --select-mode       Simple selection mode
  --multi             Allow multiple selection
  --select-related F  Output related files for a focused file
  --explain-selection Include score/reasons in related-file output
  --resume-ai-session [NAME]
                      Restore named AI session metadata (default: ai)
  --mcp-server        Run as MCP server
  --session ACTION    Session management: save, restore, or clear
  --selection-path F  Write selected paths to file on exit
  benchmark ai        Run AI benchmark scenarios (use --scenario and --iterations)
  init claude         Initialize Claude config with fileview MCP entry
  plugin init         Create plugin template file
  plugin test PATH    Test a plugin file in sandbox

Environment:
  FILEVIEW_ICONS=0            Disable icons
  FILEVIEW_IMAGE_PROTOCOL     Force image protocol: auto, halfblocks, chafa, sixel, kitty, iterm2
  FILEVIEW_HELP_KEY_STYLE     Help key style: solid, outline, plain

Exit Codes

Shell Integration

# Add to .bashrc or .zshrc
fvcd() {
  local dir=$(fv --choosedir "$@")
  [ -n "$dir" ] && [ -d "$dir" ] && cd "$dir"
}

Installation Options

# Standard install
cargo install fileview

# With Chafa support (better image quality on basic terminals)
brew install chafa  # or apt install libchafa-dev
cargo install fileview --features chafa

# Speed-optimized build (larger binary, better runtime performance)
cargo install fileview --profile release-fast

Stability

• Current channel: stable (2.3.2)
• Stable promotion criteria are documented in docs/STABILITY.md.
• As of 2026-02-04, criteria were satisfied and stable release was approved.

Lua Plugin System

Extend FileView with Lua scripts:

-- ~/.config/fileview/plugins/init.lua

-- Startup notification
fv.notify("Plugin loaded!")

-- React to events
fv.on("file_selected", function(path)
    if path and path:match("%.secret$") then
        fv.notify("Warning: Secret file!")
    end
end)

-- Custom command
fv.register_command("copy-path", function()
    local file = fv.current_file()
    if file then
        fv.set_clipboard(file)
        fv.notify("Copied: " .. file)
    end
end)

Plugin API Reference

Documentation

• Claude Code Integration - AI pair programming guide
• Keybindings - Complete keybinding reference
• Plugins - Lua plugin system
• Comparison - vs yazi, lf, ranger, nnn
• Roadmap - Product direction and release history
• Benchmarks - Performance data
• Security - Security model
• Stability - Release channel policy and alpha exit criteria
• Release Policy - Versioning, cadence, and promotion rules

License

MIT