GitHub - WillyV3/vinw: Detachable file viewer and git aware file tree.

4 min read Original article ↗

Go Bubble Tea Glamour Homebrew License

A fast, interactive file tree with dual-terminal viewer. Everything you need to start making the switch to the terminal, without losing the convenience of a full-featured file-tree.

image

"This tool is pretty sick though. you're not going to convert many emacs or vim users but I suspect there are a new crop of Claude Code-oriented devs who will give the willy stack a whirl." -User (Staff engineer)

Features

Core Features

  • Real-time git change tracking - See exactly which files have uncommitted changes (+N indicator)
  • File & directory creation - Create files (a) and directories (A) directly from the tree
  • Dual-terminal preview - Separate viewer with syntax highlighting and markdown rendering
  • Session isolation - Run multiple instances in different directories simultaneously
  • Find and Replace - Tried to make this like VScode - Tested using property-based testing library with iver 450 different replacements.
    • Navigate to selected snippet while in Find Mode -
image

Theme Selection Menu

image

Installation

Homebrew (Recommended)

brew install willyv3/tap/vinw

Build from Source

Manual Build

go build -o vinw
cd viewer && go build -o vinw-viewer

Requirements

  • Go 1.21+
  • Git
  • Skate - go install github.com/charmbracelet/skate@latest
  • GitHub CLI (optional, for repo creation)

Usage

Start vinw in one terminal:

vinw              # Current directory
vinw /path/to/dir # Specific directory

vinw will display a session ID. Use it to start the viewer in another terminal:

Controls

File Tree (vinw)

Navigation

  • j/k or ↑/↓ - Navigate files and directories
  • ← - Collapse selected directory
  • → - Expand selected directory
  • Space or Enter - Select file for viewing

File Operations

  • a - Create new file in current/selected directory
  • A - Create new directory in current/selected directory
  • d - Delete file or directory with confirmation

Toggles & Settings

  • h - Toggle hidden files and folders
  • i - Toggle gitignore filter
  • n - Toggle directory nesting (full tree vs. collapsible)
  • t/T - Cycle themes forward/backward

Other

  • v - Show viewer command
  • ? - Help menu
  • q - Quit

File Viewer (vinw-viewer)

  • ↑/↓ or mouse - Scroll content
  • e - Edit file in preferred editor (nvim, vim, nano, etc.)
  • m - Toggle mouse mode (scroll/select for copying)
  • r - Manual refresh
  • q - Quit

How It Works

Session Isolation

Each vinw instance generates a unique session ID based on the directory path. This allows you to:

  • Run multiple vinw instances in different directories
  • Connect the correct viewer to each instance
  • Keep sessions completely isolated

Git Integration

vinw automatically:

  • Detects git repositories
  • Tracks uncommitted changes (shows +N next to modified files)
  • Creates GitHub repositories if they don't exist (with gh CLI)
  • Respects .gitignore patterns (toggleable)

File Creation

When you press a or A:

  • A prompt appears asking for the file/directory name
  • The new item is created in the currently selected directory (or parent if a file is selected)
  • The tree automatically refreshes to show the new item
  • Existing files/directories are protected (won't overwrite)

File Deletion

When you press d:

  • A confirmation prompt appears showing the file/directory to delete
  • Non-empty directories display a warning with item count
  • Press y to confirm deletion or n/esc to cancel
  • The tree automatically refreshes after deletion
  • This action cannot be undone - use with caution

Testing

Run the test suite:

Development

make build        # Build both binaries
make clean        # Remove binaries
make run          # Run vinw
make run-viewer   # Run viewer

Architecture

vinw is built completely within the Charmbracelet ecosystem:

Feedback

I worked hard on vinw and the vinw-workspace companion. If you end up trying it and want to leave feedback, I'd appreciate it. I want to make it better so more people use it. This is the hard product part. Bear with me.

Main Application (filetree and detached viewer/editor)

brew install willyv3/tap/vinw

https://github.com/WillyV3/vinw

Companion app (tmux workspace launcher)

brew install willyv3/tap/vinw-workspace

https://github.com/WillyV3/vinw-workspace

Feedback Form: https://forms.gle/fNhsLD5tSJxL2Fu4A

-WillyV3

License

MIT