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

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
hjklfor the grid or list,/orctrl+ffor 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 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 — every binding, scrollable in short windows. | Settings — theme, behavior, layout and image protocol, with a live preview. |

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:
ffmpegfor video frames - Optional:
pdftoppmfrom 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
¶
There is no documentation for this package.



