fleek

command module
v0.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 38 Imported by: 0

README

fleek

Linux Kitty graphics MIT

A terminal file manager with real thumbnails and a responsive grid/list layout, built for Ghostty and tmux.

fleek showing a grid of image thumbnails

Actual 200×60 half-block capture. Demo artwork is generated for the screenshots.

Why fleek?

  • See the file before you open it. Images, videos and PDFs get real 3:2 thumbnails, loaded lazily and cached on disk.
  • Built for the terminal you already use. Kitty graphics with Unicode placeholders in Ghostty, Kitty and WezTerm, including inside tmux. Everything else gets a colored half-block fallback.
  • Fast to drive. Arrows or hjkl for the grid or list, / or ctrl+f for recursive search, and a right-click menu for copy, cut, rename, trash and new folders.
  • Fits the window you have. Full sidebar on wide terminals, an icon rail in the middle, a compact list on a phone-sized 40×23 window.
  • One binary, your config. A single Go binary with TOML themes, layout, sorting and extra sidebar places. No daemon, no Electron.

Screenshots

All screenshots are half-block captures from the current build.

Full-screen viewer File actions
Full-screen image viewer File actions menu
Full-screen viewer — space opens the selected image; arrows browse. File actions — right-click or m to open, copy, cut, rename or trash.
Keyboard help Settings
Keyboard help panel Settings window
Keyboard help — every binding, scrollable in short windows. Settings — theme, behavior, layout and image protocol, with a live preview.

fleek in a phone-sized terminal

Phone-sized terminal — 40×23. Below 60 columns the grid becomes a compact list.

Features

  • 3:2 thumbnails for images, videos and PDFs
  • Nerd Font folder tiles and file-type icons
  • Places sidebar with mounted filesystems and free space
  • Right-click a folder to add it to the sidebar, or remove it again
  • Responsive grid on desktop, compact list on phones
  • Selection borders, breadcrumbs and navigation history
  • Recursive search across the current tree (/)
  • Copy, cut, paste, rename, trash and new-folder actions
  • Right-click context menu, plus keyboard equivalents
  • Full-screen viewer with arrow-key browsing
  • Lazy thumbnail loading and a disk cache
  • Kitty graphics for Ghostty/Kitty/WezTerm, with a half-block fallback
  • Catppuccin Mocha palette by default
  • TOML configuration for theme, layout, behavior and extra places
  • In-app settings window with live theme preview and save-to-TOML

Requirements

  • Linux
  • Go 1.27 or newer to build
  • A terminal with a Nerd Font installed
  • Optional: ffmpeg for video frames
  • Optional: pdftoppm from poppler for PDF pages

Install

From a checkout:

git clone https://github.com/StefanVonRanda/fleek.git
cd fleek
./install.sh

install.sh builds fleek, installs it to ~/.local/bin (or $PREFIX/bin), and writes a starter config to ~/.config/fleek/config.toml if you do not have one yet.

Or use Go directly:

go install github.com/StefanVonRanda/fleek@latest

Run fleek with no arguments to open the current directory:

cd ~/Pictures
fleek

Pass a directory to open it, or a file to open its parent with that file selected.

Usage

Key Action
← ↑ ↓ →, hjkl move in the grid or list
enter / double-click open folder or file
double-click image full-screen viewer
space preview selected image
c / x / v copy / cut / paste
F2 rename
n new folder
Del move to trash
m / right-click file actions menu
backspace parent folder
alt+← / alt+→ back / forward
~ home
. show or hide dotfiles
/ or ctrl+f recursive search
tab jump between the grid and sidebar
r refresh
s / ctrl+, settings and theme
? help
q / ctrl+c quit (ctrl+c works from any view)

Mouse clicks select; double-click opens. The wheel scrolls. Sidebar places, breadcrumbs and toolbar icons are clickable. Right-click a folder to add or remove it from the sidebar.

Search results show paths relative to the current directory. esc closes search and restores the folder; enter opens the selected result.

Small terminals

Below 90 columns the sidebar collapses to a three-column icon rail; below 36 columns it is hidden and the grid uses the full width. Below 60 columns the grid becomes a compact list. The help panel scrolls with j/k, arrow keys or the wheel. Search expands to the full path bar under 50 columns, and menus and dialogs size themselves to the window.

Configuration

fleek reads ~/.config/fleek/config.toml ($XDG_CONFIG_HOME/fleek/config.toml) by default. Use --config PATH or FLEEK_CONFIG to load another file. examples/config.toml is the complete annotated example.

Press s (or ctrl+,) to open the settings window. It edits the theme palette, behavior, layout and image protocol with a live preview. ctrl+s (or s) saves to the active config file and esc discards the changes. Saving settings or a bookmark rewrites the file, so comments in a hand-edited config are not preserved.

[theme]
background = "#1e1e2e"
accent = "#cba6f7"
text = "#cdd6f4"

[behavior]
show_hidden = false
sort = "name"              # name, size, modified
directories_first = true

[layout]
sidebar_width = 20         # 14-32 (preferred; hidden below 36 columns)
card_width = 25            # 25-40
gap = 2                    # 1-4

[images]
protocol = "auto"          # auto, tgp, halfblock

The full palette, every layout key and custom places live in examples/config.toml.

Extra places
[[places]]
label = "Code"
path = "~/code"
icon = "code"
color = "#89b4fa"

Available icon names are home, download, document, music, picture, video, code, trash, disk, bookmark and folder.

Right-click a folder and choose Add to sidebar to append it to this list. The same menu removes bookmarks you added.

Environment overrides
Variable Purpose
FLEEK_PROTOCOL tgp or halfblock
FLEEK_CACHE_DIR thumbnail cache root (default: ~/.cache/fleek)
FLEEK_FONT path to a Nerd Font used to render large folder glyphs
FLEEK_CONFIG alternative config file path

Thumbnails and preview images are cached under ~/.cache/fleek/thumbs. The cache is safe to delete.

Images and tmux

fleek chooses the image renderer at startup:

  • Ghostty, Kitty, WezTerm: Kitty graphics with Unicode placeholders
  • everything else: colored half blocks

Inside tmux, Kitty graphics require passthrough:

set -g allow-passthrough on
set -ga terminal-features ',xterm-ghostty:RGB'

The second line advertises truecolor support to tmux. Without it, tmux may quantize the image-ID colors and thumbnails will not render correctly.

Force a renderer when needed:

FLEEK_PROTOCOL=halfblock ./fleek ~/Pictures
FLEEK_PROTOCOL=tgp ./fleek ~/Pictures

The screenshots above use the half-block renderer: grid, viewer. It is also what terminals without Kitty graphics show.

Current limitations

  • File operations act on a single selection; multi-select is not implemented yet.
  • Linux is the supported platform for mount and font discovery.
  • Sixel is not supported.
  • Video and PDF thumbnails require the optional external tools above.

License

MIT

Documentation

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL