vcom/README.md

vcom

vcom is a two-pane terminal file manager with a fast built-in info/preview panel for the active selection.

Why vcom

• Two-pane workflow focused on keyboard speed
• Built-in preview/info pane for the active selection
• Asynchronous copy/move with progress and background mode
• Theme support and configurable layout/columns

Screenshots

Build and run

Run directly:

go run ./cmd/vcom

Build local binary:

go build -o vcom ./cmd/vcom

Installation

NixOS / Nix

Run directly from the flake:

nix run github:vrubelroman/vcom?ref=v0.1.9

Install into user profile:

nix profile add github:vrubelroman/vcom?ref=v0.1.9

The Nix package wraps vcom with ueberzugpp in PATH, so image preview works in non-kitty terminals out of the box.

Debian / Ubuntu

Download the release .deb for v0.1.9, then install:

sudo apt install ./vcom_0.1.9_amd64.deb

The Debian package declares ueberzug (or ueberzugpp where available) as a dependency for image preview outside kitty.

Arch Linux

A PKGBUILD is included in the repository:

makepkg -si

The Arch package depends on ueberzugpp, so non-kitty image preview is installed together with vcom.

Font requirement (icons)

For file icons, vcom expects a Nerd Font in your terminal profile.

Default behavior is ui.icon_mode = "auto":

• if a Nerd Font is detected, vcom uses Nerd icons
• if not, vcom falls back to ASCII icons automatically

You can force behavior in config:

• ui.icon_mode = "nerd": always use Nerd icons
• ui.icon_mode = "ascii": always use ASCII icons

Installing a Nerd Font

Ubuntu / Debian:

wget -qO /tmp/JetBrainsMono.zip https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip
mkdir -p ~/.local/share/fonts/JetBrainsMonoNerd
unzip -o /tmp/JetBrainsMono.zip -d ~/.local/share/fonts/JetBrainsMonoNerd
fc-cache -fv

Arch Linux:

sudo pacman -S ttf-jetbrains-mono-nerd

Or via AUR helper:

yay -S nerd-fonts-jetbrains-mono

NixOS / Nix:

Add to your /etc/nixos/configuration.nix:

fonts.packages = with pkgs; [ nerd-fonts.jetbrains-mono ];

Or install imperatively:

nix profile install nixpkgs#nerd-fonts.jetbrains-mono

Configuring terminal to use the installed Nerd Font

After installing, set JetBrainsMono Nerd Font (or another Nerd Font) as the terminal font:

• GNOME Terminal: Preferences → Profile → Text → Custom font → choose JetBrainsMono Nerd Font
• Konsole: Settings → Edit Current Profile → Appearance → choose a Nerd Font profile
• Alacritty: set font.normal.family: "JetBrainsMono Nerd Font" in ~/.config/alacritty/alacritty.yml
• Kitty: set font_family JetBrainsMono Nerd Font in ~/.config/kitty/kitty.conf
• Foot: set font=JetBrainsMono Nerd Font:size=11 in ~/.config/foot/foot.ini
• WezTerm: set font = wezterm.font("JetBrainsMono Nerd Font") in ~/.config/wezterm/wezterm.lua
• Windows Terminal: Settings → Profiles → Defaults → Appearance → Font face → choose JetBrainsMono Nerd Font

Preview mode (F9 / i) temporarily replaces the inactive pane and shows:

• directory listing preview
• text file preview with syntax highlighting
• image metadata (format + dimensions)
• safe fallback for binary files

Configuration

Optional config lookup order:

1. -config /path/to/vcom.toml
2. ./vcom.toml
3. ./config/vcom.toml
4. $XDG_CONFIG_HOME/vcom/vcom.toml
5. ~/.config/vcom/vcom.toml

Reference config: vcom.toml

Icon mode example:

[ui]
icon_mode = "auto" # auto | nerd | ascii

Themes

Built-in themes (use T to cycle or set ui.theme in config):

• catppuccin-mocha (default)
• catppuccin-lavender
• tokyo-night
• gruvbox-dark
• gruvbox
• nord-frost
• nord
• ayu-dark
• breeze
• cyberpunk
• dracula
• eldritch
• kanagawa
• kanagawa-paper
• rose-pine
• solarized-dark
• vesper

Releases

Pushing a tag like v0.1.9 triggers GitHub Actions release workflow (.github/workflows/release.yml) which:

• runs tests
• vendors Go modules
• builds release binary
• builds Debian package
• publishes release assets

Release artifacts:

• vcom-v0.1.9-x86_64-unknown-linux-gnu.tar.gz
• vcom_0.1.9_amd64.deb
• vcom-v0.1.9-checksums.txt

Notes

• File creation time depends on filesystem/OS support; unavailable values are shown as n/a.

Architecture notes: docs/architecture.md