Quattro Files

Quattro Files is a fast, keyboard-first visual filesystem browser for the Omarchy Quattro shell. It browses files in place—there is no import step, no library, and no copying of user media.

It combines an Eagle-style variable-height media grid, macOS-like Quick Look, and the terse keyboard grammar of tools such as Neovim, Yazi, fzf, and lazygit. Images keep their natural aspect ratio, videos get cached thumbnails and native playback, and ordinary folders and files remain first-class citizens.

Project status

Version 1 is in active development and real-world testing. The core browser is usable today, but expect follow-up releases as it is exercised against more hardware, themes, codecs, and large personal media collections. Updates may arrive quickly during this testing period.

It is not yet submitted to the Omarchy plugin marketplace. Marketplace submission is planned after this public testing period.

Please report reproducible problems through GitHub Issues.

Highlights

• Real filesystem browsing with no imports, proprietary library, or path changes
• Virtualized waterfall layout that preserves image and video aspect ratios
• Full-canvas image and video Quick Look with zoom, pan, seek, and metadata
• Geometric hjkl navigation, marks, batch actions, and searchable command palettes
• Fuzzy directory jumping with bookmarks, recents, and optional zoxide frecency
• Asynchronous metadata and thumbnail helper with a disposable disk cache
• Native Omarchy semantic colors, spacing, borders, and live theme behavior
• Normal Hyprland toplevel behavior: tile it, resize it, or make it fullscreen

Requirements

• Omarchy 4 / the current Quattro plugin host
• Qt 6 with QtMultimedia and its FFmpeg backend
• Python 3.11 or newer (standard library only)
• ffmpeg and ffprobe
• inotify-tools, gio, xdg-open, and wl-copy
• Optional: zoxide contributes frecency-ranked directories to the jumper
• Optional: ImageMagick improves fallback decoding for formats FFmpeg rejects

These are present on a standard current Omarchy installation. The helper has no network access and uses argument arrays for every external process.

Install

Install directly from GitHub:

omarchy plugin add https://github.com/kailbert/omarchy-plugin-mediabrowser.git --enable

For local development from this checkout:

mkdir -p ~/.config/omarchy/plugins
ln -s "$(pwd)" ~/.config/omarchy/plugins/quattro.files

Then validate, rescan, and enable it:

# Validate the real checkout, not the development symlink (the validator
# intentionally rejects symlinks inside the path it validates).
omarchy plugin validate "$(pwd)"
omarchy shell shell rescanPlugins
omarchy plugin enable quattro.files

Install the included desktop entry to make Quattro Files searchable in Omarchy's Apps launcher:

install -Dm644 data/quattro-files.desktop ~/.local/share/applications/quattro-files.desktop

Launch

omarchy shell shell toggle quattro.files '{}'

Open a particular directory:

omarchy shell shell summon quattro.files '{"path":"/home/me/Pictures"}'

Recommended Hyprland binding (add this through your normal user bindings, without replacing an existing SUPER+E binding):

o.bind("SUPER + E", "Quattro Files", "omarchy shell shell toggle quattro.files '{}'")

After editing user Hyprland bindings, run hyprctl reload and hyprctl configerrors.

Keyboard

Key	Action
h j k l or arrows	Move selection through the masonry layout
Enter or o	Open folder; Quick Look media; open other files
Space	Open Quick Look
gg / G	Select first / last item
n / N	Next / previous item in strict sort order
zz / zt / zb	Place the selected tile at center / top / bottom
Ctrl+U / Ctrl+D	Scroll half a page
Backspace	Parent directory
H / L	Back / forward
gh / gp	Home / Pictures
/ or Ctrl+F	Filter current folder
c	Open the fuzzy recent/bookmark/directory jumper
b	Bookmark or unbookmark the current directory
Ctrl+L	Edit location
. or Ctrl+H	Toggle hidden files
y	Copy selected path
x / v / V	Toggle mark / visual mark / mark a range
Y / X / p	Stage a copy / stage a move / paste into this folder
a / : / ,	File actions / all commands / view and sort palette
i	Open media in Quick Look with its information panel
r / R	Rename / refresh
d	Move to Trash after confirmation
s	Show or hide the sidebar
Shift+S	Browser settings
+ / - (or = / -)	Increase / decrease thumbnail size
Shift + + / Shift + -	Increase / decrease grid gap
F11	Toggle fullscreen for the current workspace
q or Escape	Close transient UI or the browser
?	Show the complete keyboard reference

Quick Look adds these controls:

Key	Action
q or Escape	Close Quick Look
Space	Close an image, or play/pause a video
h / l, [ / ], or Shift+Left / Shift+Right	Previous / next media in current sort order
Left / Right	Previous/next image; seek video ±5 seconds
j / k on video	Volume down / up
m	Mute/unmute video
i / o / y	Toggle information / open externally / copy path
f or 0	Fit image to the preview
1	Show the image at true 100%
+ / -	Zoom image in/out
Mouse wheel	Zoom around the pointer
Mouse drag	Pan a zoomed image
c or Tab	Hide/show Quick Look controls

The image or video now uses the complete Quick Look canvas. Controls sit over the media instead of reserving a footer; hide them with c, Tab, or the Hide button. The default fit view never enlarges an image beyond its native resolution; explicit zoom remains available. Double-click an image to toggle between fit and 100%.

Right-click an item for Open, Open with default, Copy path, Rename, and Move to Trash. Permanent deletion is intentionally unavailable.

An active folder filter always keeps its input visible and shows the term in the empty state. Navigating to another directory clears the filter so it cannot silently hide that directory's contents.

Press c for a native fzf-style directory jumper. Bookmarks and recently used directories are ranked first; installed zoxide history is folded in as an optional frecency source. It also asynchronously scans a bounded five-level tree under Home (or the current non-Home root), streams results progressively, fuzzy-ranks as you type, and supports arrows or Ctrl+N/Ctrl+P plus Enter. The filesystem scan runs only when the jumper is opened.

Window and settings

Quattro Files is a normal Hyprland toplevel, so it tiles, resizes, and stays on the workspace where it was opened. This avoids the all-workspace behavior of a layer-shell overlay. Use F11 or the toolbar button when you want the original fullscreen browsing experience.

The gear button (or Shift+S) opens global browser settings for continuously adjustable thumbnail width, grid gap, sidebar width, filename visibility, and folders-first sorting. A compact thumbnail slider also appears directly in the toolbar when the window is wide enough. Appearance and browsing preferences persist between launches.

Architecture and data

The QML panel runs inside the existing omarchy-shell and owns a supported Quickshell FloatingWindow; it is not a duplicate shell. A small persistent Python helper streams directory entries and performs probing/thumbnail work on three bounded worker threads. Directory generations cancel obsolete queued thumbnail work when the user moves elsewhere. Only tiles inside a one-viewport overscan region exist as QML objects, and the virtual model is reconciled in place instead of recreated while scrolling, so directories containing thousands of files do not instantiate thousands of image delegates.

Disposable thumbnails are stored under $XDG_CACHE_HOME/quattro-files/thumbs (falling back to ~/.cache/quattro-files/thumbs). Cache keys include path, size, nanosecond mtime, and target width. Convenience state is stored under $XDG_STATE_HOME/quattro-files/state.json.

Removing either directory is safe. Quattro Files never stores original media.

Remove

omarchy plugin remove quattro.files --yes
rm -rf ~/.cache/quattro-files ~/.local/state/quattro-files
rm ~/.local/share/applications/quattro-files.desktop

The final cache/state cleanup is optional and should only be run if those exact paths are the intended targets.

Scope

The MVP previews images, animated GIFs, and video. Generic files remain browsable and open with the system default application. PDF/text Quick Look, global indexing, tags, network-share setup, permanent deletion, and recursive search are intentionally outside this release.

Development and feedback

This repository intentionally has no telemetry, network service, media upload, or proprietary database. When reporting a bug, avoid attaching personal media or unredacted filesystem paths. A synthetic reproduction and the relevant Omarchy/Qt/FFmpeg versions are usually enough.

Before submitting a change, run:

qmllint qml/*.qml
python3 -m py_compile helper/quattro-files-helper
desktop-file-validate data/quattro-files.desktop
omarchy plugin validate "$(pwd)"
git diff --check

License

MIT