╔══╦ ╦╔═╗╔═╗╔╗╔╔═╗╦═╗
╠══╚╦╝╔═╝║╣ ║║║║ ║╠╦╝
╩   ╩ ╚═╝╚═╝╝╚╝╚═╝╩╚═

Fyzenor

A modern, blazing-fast terminal file manager built in C++ with live previews, async workflows, and a polished three-column interface.

Maintainer

@Bimbok Creator / Maintainer

_{Fyzenor is designed and maintained by Bimbok.}

---

⚡ Introduction

Fyzenor is a lightweight, high-performance terminal file manager engineered from the ground up with modern C++17. It is designed to bridge the gap between the raw power of the command line and the visual feedback of modern GUIs.

With its asynchronous architecture, Fyzenor ensures that heavy operations like directory size calculation and media preview generation never block the UI, providing a "blazing fast" experience even on large filesystems. Whether you are a developer, a system administrator, or a power user, Fyzenor allows you to navigate and manage your files with the speed of thought.

🌐 Official Documentation: fyzenor.vercel.app

---

🖼️ Interface Preview

---

🚀 Key Features

Feature	Description
Three-Column Layout	Navigate with a Miller-style layout showing pinned items, parent/current directories, and a live preview pane.
2D Grid View Mode (V)	Switch dynamically between 3-column Miller mode and a modern 2D card grid with high-res thumbnails, 2D directional navigation, and aspect-ratio letterboxing.
Asynchronous Tabs	Open multiple directories in native tabs, navigating easily with [/] and number keys 1-9, preserving your selections.
Interactive Shell Commands	Execute shell commands globally with :. Supports foreground utilities, background tasks (&), and path placeholders ($f/$s).
Bulk Rename via Editor	Select multiple files and press r to rename them all at once inside your default text editor (e.g. nvim, nano).
Smart Copy Resumption	Resumes interrupted file copies block-by-block (seekg/seekp) by comparing file sizes and copying only the remaining bytes.
Task Play/Pause Controls	Suspend (pause) and resume background copy, move, delete, zip, and extract tasks directly from the task list.
Drag & Drop Integration	Drop files directly into the terminal window to Copy/Move them, or press Ctrl-D to drag files out into GUI applications (via ripdrag or dragon).
Lazygit Integration	Launch lazygit directly in your current directory with Ctrl+G. Displays as a centered, bordered popup overlay when inside tmux.
Freedesktop Trash System	Move items to trash (d) and restore/empty them in-build. Integrates home trash and local partition trash folders.
Undo Trash Action (u)	Undo the last move-to-trash action instantly, restoring items back to their original paths.
Dynamic Disk Space Status	Displays partition name, progress bar, percent used, and free space dynamically for the current drive.
Dynamic Empty Folder Icons	Instantly identifies empty directories ( ) versus populated ones ( ) using fast metadata caching.
Simultaneous Multi-Open	Open all selected files simultaneously; code/text files load in a single editor, media in an mpv playlist, others in background launchers.
Robust Symlink Management	Custom link icons (󰌹), detailed resolution preview (detects broken paths), and quick absolute symlink pasting with Shift+Y (Y).
Dynamic Sorting Modes	Toggle sorting order dynamically by pressing s, cycling between Name, Size (Desc), and Date Modified (Desc).
Async Media Preview	Generate high-resolution image and video previews asynchronously using the Kitty Graphics Protocol with zero flicker across Kitty, Ghostty, and WezTerm.
Modern & Polished UI	A clean, minimal interface featuring rounded corners, optimized spacing, and an elegant color palette designed for long-term readability and comfort.
Syntax-Aware Text Preview	Preview code and text files with bat or batcat, with fallback to plain text when needed.
Background Folder Sizing	Directory sizes are calculated asynchronously and update in place while you keep moving.
Vim-Style Navigation	Fast keyboard-driven navigation with h, j, k, l, g, G, arrow keys, and enter-based traversal.
Nerd Fonts Integration	Rich iconography for directories, archives, media, and code file formats for faster visual identification.
Multi-Selection & Bulk Actions	Select multiple files and apply copy, cut, paste, delete, and zip operations efficiently.
Persistent Pins	Save frequently used directories to ~/.fm_pins and jump back to them instantly.
Flicker-Free Rendering	Optimized redraw behavior keeps the interface smooth while reducing unnecessary terminal updates.
Rich File Operations	Create files/folders, rename entries, zip selections, copy absolute paths, and manage content without leaving the TUI.
Theme Support	Customize the UI through ~/.config/fyzenor/theme.toml, with optional Matugen-powered wallpaper theming.
Archive Previewer	Inspect contents of .zip, .tar.gz, .rar, .7z archives directly in the TUI preview pane without extracting them.
Media Metadata Inspector	Read codec names, bitrates, dimensions, sample rates, title, and artist metadata tags for images, audio, and video tracks.
Custom Key Macros	Map single-key binds in ~/.config/fyzenor/keys.toml to run terminal macros with path placeholders ($f, $s).
Editor Integration	Opens text/code files with your configured editor via $EDITOR or $VISUAL, with sensible fallbacks.
Content Search (ripgrep)	Search for file contents under the current directory using ripgrep, displaying relative paths and supporting vim-like navigation.
Manual Cache Refresh	Refresh directory contents and invalidate sizes/previews cache instantly using F5 / Ctrl+R.
Dual-Pane Mode	Toggle (F2) side-by-side active file listings for drag-free copying, with easy tab focus switching (Tab).
Visual Disk Usage Mode (U)	Interactive ncdu / gdu-style disk usage visualizer with dynamic proportional bar meters ([████████░░] 74.2%), folder percentage, and auto-sorting.
Context-Aware Mouse Scrolling	Hover and scroll your mouse wheel over any pane: middle pane scrolls files, preview pane scrolls long code/text/archives/directories with live indicators ([1-40/350]), and pinned pane scrolls bookmarks.
Device Detection & Mounts	Detect, mount, unmount, and navigate connected USB block drives and mobile phones (Android MTP) natively without needing Nautilus.
Live Auto-Updates (inotify)	Automatically detects filesystem changes (creations, deletions, renames) in the current directory and refreshes the TUI instantly.

---

🛠️ Tech Stack

Core

• Language: C++17
• UI Layer: ncursesw
• Concurrency: C++ threads with mutex-protected async workflows
• Filesystem: std::filesystem

External Tools

• Preview Rendering: Kitty Graphics Protocol
• Image & Video Thumbnailing: ffmpeg
• Syntax Highlighting: bat or batcat (rendered in color via custom ncurses ANSI parser)
• File Content Searching: ripgrep (rg)
• Archive Support: zip
• Clipboard Support: xclip, wl-copy, or pbcopy

---

🛠️ Prerequisites

To unleash the full power of Fyzenor, especially image previews, your system needs a few core components.

1. A Compatible Terminal

To enjoy high-resolution image and video previews, use a modern terminal emulator that supports the Kitty Graphics Protocol:

• Kitty: First-class support with native Kitty Graphics Protocol, synchronized frame updates (DEC Mode 2026), and smart cell preservation for a zero-flicker experience.
• Ghostty: Native Kitty Graphics Protocol support with GPU-accelerated tear-free rendering.
• WezTerm: Full native support with memory-safe GPU texture pruning (d=A) and atomic in-place image swapping (a=T,i=1).
• Konsole: Compatible with Kitty graphics protocol.

Note for other terminals: If you use Alacritty, GNOME Terminal, Foot, xterm, or another terminal without Kitty Graphics support, Fyzenor works out-of-the-box! Media previews gracefully fall back to detailed file metadata and syntax-highlighted text previews without any visual artifacts.

2. System Dependencies

On Debian-based or Ubuntu-based systems:

sudo apt update
sudo apt install build-essential libncursesw5-dev ffmpeg zip bat xclip wl-copy ripgrep

On Fedora-based systems:

sudo dnf update
sudo dnf install gcc gcc-c++ make ncurses-devel ffmpeg zip bat xclip wl-clipboard ripgrep

On Arch Linux-based systems:

sudo pacman -Sy
sudo pacman -S base-devel ncurses ffmpeg zip bat xclip wl-clipboard ripgrep

On Termux (Android) environments:

pkg update
pkg install clang cmake ndk-sysroot ncurses-utils ffmpeg zip bat ripgrep

• libncursesw, ncurses, or ncurses-utils: Essential for wide-character terminal rendering.
• ffmpeg: Powers asynchronous thumbnail generation for images and videos.
• zip: Required for built-in archive creation.
• bat or batcat: Used for syntax-highlighted text previews.
• xclip / wl-copy / pbcopy: Used for the copy-path feature.

---

⚙️ Installation & Update

The easiest way to install or update Fyzenor is using the universal installation script.

Windows Compiler Compatibility

Fyzenor requires a compiler with proper C++17 filesystem support.

Older MinGW GCC versions (such as GCC 6.x) may fail during compilation with:

fatal error: filesystem: No such file or directory

Recommended environments for Windows users:

• MSYS2 MinGW-w64
• WSL (Windows Subsystem for Linux)

Recommended compiler versions:

• GCC 8+
• Clang 7+

You can check your compiler version using:

g++ --version

Smart Installer

# 📦 Install Stable Release (v4.3.0 - Default)
curl -fsSL https://raw.githubusercontent.com/Bimbok/fyzenor/main/install.sh | bash

# 🧪 Install Development Channel (Beta)
curl -fsSL https://raw.githubusercontent.com/Bimbok/fyzenor/main/install.sh | bash -s -- --beta

Manual Installation & Updates

# 1. Clone the repository
git clone https://github.com/Bimbok/fyzenor.git

# 2. Enter the repository
cd fyzenor

# 3. Run the installer (supports --beta, --stable, --uninstall, --purge)
./install.sh

🗑️ Uninstallation

To uninstall Fyzenor cleanly at any time:

# Standard uninstallation (removes binary, 'fm' symlink, desktop entry, and icon)
./uninstall.sh
# Or via curl:
curl -fsSL https://raw.githubusercontent.com/Bimbok/fyzenor/main/uninstall.sh | bash

# Complete purge (also removes ~/.config/fyzenor and ~/.fm_pins)
./uninstall.sh --purge
# Or using the universal installer:
./install.sh --uninstall --purge

The installer:

1. Checks required build tools (compiler, CMake, Ncurses, Lua) and runtime dependencies.
2. Compiles the C++ source using all available CPU cores in parallel (-j$(nproc)).
3. Installs fyzenor into /usr/local/bin/ (or Termux $PREFIX/bin).
4. Creates an fm symlink for rapid terminal access.
5. Installs the desktop application shortcut and branding icon globally.
6. Initializes default configuration files in ~/.config/fyzenor/ if missing.

---

🚀 Quick Start

If you want to build and run Fyzenor manually instead of using the installer:

git clone https://github.com/Bimbok/fyzenor.git
cd fyzenor
mkdir -p build && cd build
cmake ..
make
./fyzenor

This route is useful if you want direct control over compilation or want to test local modifications before installation.

🔍 Rich Previews

Archive Tree Previewer

Fyzenor reads .zip, .tar.gz, .tgz, .7z, and .rar archive tables on the fly without extraction. It leverages background listing tools (unzip, tar, 7z, unrar) to display a neat directory layout right in the preview pane.

Media Metadata Inspector

Get information about your media files (.mp4, .mp3, .mov, .png, .jpg, etc.) dynamically. The preview worker uses mediainfo or ffprobe (via ffmpeg) to show streams metadata, codecs, channels, sample rates, and tags.

PDF Text Layout Previewer

If pdftotext (from poppler-utils) is installed on your system, Fyzenor asynchronously extracts and renders the formatted text layouts of the first 3 pages of .pdf files directly in the preview pane.

󰊢 Git & Lazygit Integration

Fyzenor features native integration with lazygit to make repository staging and committing seamless:

• Launch Hotkey: Press Ctrl+G in normal view mode to launch lazygit directly inside your currently active directory.
• TMUX Floating Popup Modal: If Fyzenor is running inside a active tmux session, it leverages tmux display-popup to spawn lazygit as a centered, floating overlay window (taking up 85% of screen width and height). This creates a gorgeous desktop-like modal experience without leaving your TUI layout.
• Clean Full-Screen Fallback: Outside of tmux, the terminal is safely suspended, lazygit takes over full-screen, and upon exiting, control is handed back to Fyzenor.
• State Auto-Reloading: Once you close lazygit, Fyzenor instantly reloads all directory files and statuses, ensuring checkout changes, branch updates, or resets reflect immediately in the browser pane.

🚀 What's New in v4.3.0

🖼️ 2D Grid View & Visual Media Explorer (Shift+V / V)

Fyzenor introduces a native 2D Grid View designed for fast, beautiful visual exploration of photos, wallpapers, video clips, and directories:

• Dynamic Card Grid Layout: Press V (Shift+V) or click the [󰕰 Grid: V] header badge to instantly switch between 3-column Miller mode and an adaptive 2D thumbnail card grid that automatically packs cards into rows and columns based on your terminal width (cardW = 16, cardH = 7).
• True Aspect-Ratio Letterboxing: Generates high-resolution 280x160 RGBA letterboxed Kitty image thumbnails with automatic padding. Eliminates stretched or squished thumbnails across portrait, landscape (16:9, 4:3), and square media.
• Universal 24-Bit TrueColor ANSI Fallback: In terminals without Kitty graphics support, Fyzenor generates a 4-row Unicode half-block (▀) fallback with TrueColor fidelity (\033[38;2;...;48;2;...m).
• High-Visibility Selection Prominence: Active cards feature bold double-line borders (╔═◆═╗), a centered selection diamond (◆), and a full-width filename pill (▸ name ◂) with high-contrast background highlights.
• Zero-Flicker Focus Transitions: Direct Kitty graphics placements are tracked per terminal cell, eliminating premature clearing or blanking when jumping focus between the Pinned menu and Grid View.
• Safe In-Memory Generation for Cache & Trash: Viewing ~/.cache/fyzenor/previews or ~/.local/share/Trash generates and renders thumbnails completely in memory (or directly reads existing cache files) without creating recursive disk cache files or triggering inotify reload loops.
• 2D Directional Navigation: Intuitive navigation with h (left), j (down), k (up), l (right), arrow keys, Home/End, PgUp/PgDn, and mouse clicks.

🌌 Native Neovim Integration (fyzenor.nvim)

Fyzenor now includes a dedicated Neovim plugin inspired by yazi.nvim! Run Fyzenor directly inside Neovim in a centered floating terminal window:

• Floating Window: Centered modal with background dimming and customizable borders.
• Netrw Directory Hijacking: Automatically replaces netrw when opening directory buffers (nvim . or :edit dir/).
• Multi-Buffer & Split Loading: Select multiple files with Tab or Space and open them across splits (<c-v>, <c-x>), tabs (<c-t>), or buffer lists (:args).
• CWD Synchronization: Automatically updates Neovim's :cd when closing Fyzenor.
• Quick Install (lazy.nvim):

  {
    "Bimbok/fyzenor",
    event = "VeryLazy",
    opts = { open_for_directories = true, change_neovim_cwd_on_close = true },
    keys = {
      { "<leader>e", "<cmd>Fyzenor<cr>", desc = "Open Fyzenor (current file)" },
      { "<leader>E", "<cmd>Fyzenor cwd<cr>", desc = "Open Fyzenor (project root)" },
      { "<leader>fe", "<cmd>FyzenorToggle<cr>", desc = "Toggle Fyzenor" },
    },
  }

📊 Visual Disk Usage & Bar Graph Mode (U)

• Single-Key Storage Analysis: Press U in normal mode to turn any directory listing into a visual storage visualizer (like ncdu).
• Proportional Bar Graphs: Unicode proportional bars (e.g. ██████░░░░ 60%) rendered alongside directory sizes.
• Non-Blocking Background Scanning: Deep directory calculations happen asynchronously on worker threads with zero UI latency.
• Circular Symlink Protection: Inode-level cycle detection prevents infinite recursion hangs.

🖱️ Mouse Controls & Pane-Aware Scrolling

• Pane-Aware Hover Scrolling: Hover your mouse over the parent, current, pinned, or preview pane and scroll the wheel to scroll that specific pane directly without clicking or changing focus!
• Preview Scrolling: Smoothly scroll long text, code, or directory previews with the mouse wheel or Ctrl+E (down) / Ctrl+Y (up).

🎯 Yazi-like Cursor Tracking Across Sorting (s)

• Locked-in Item Tracking: When you hover over a file or folder and press s to change sort modes (Alphabetical ➔ Size ➔ Date), the file list is rearranged, but your cursor automatically tracks and stays locked onto that exact file or folder, adjusting scroll offsets smoothly without jumping to the top.
• Stable Background Size Computation: As directory sizes compute asynchronously in the background, your active selection never flutters or switches items when the list re-orders.

🧭 Per-Directory Cursor Memory (dirCursorHistory)

• Folder Entry & Exit Memory: When you enter a subfolder and return back to the parent directory (h / Left / Backspace), Fyzenor remembers and focuses the directory you just came from.
• Deep Directory State Memory: Every visited directory retains its last active cursor position and scroll offset. Navigating back and forward across history (Ctrl+O / Ctrl+P) restores your cursor directly to the file you were inspecting.

🎨 Universal 256-Color Engine (hexTo256)

• TMUX & Neovim Terminal Native: Uses exact Euclidean RGB matching to map hex themes (theme.toml) into 256-color ANSI space. Renders identically inside tmux, Neovim terminal (:terminal), Kitty, Alacritty, and Foot without washed-out colors or crude 8-color fallbacks.
• Immune to Dynamic Palette Reloads: 256-color cube indices are fixed and immune to terminal theme reloads (e.g. Matugen wallpaper changes). Press Ctrl+R or F5 to re-read theme.toml and refresh the screen instantly.

📋 Modal Clipboard Pasting & Input Enhancements

• Full Clipboard Paste Support: Supports Ctrl+V, Ctrl+Shift+V, and terminal bracketed paste (\033[200~) inside all modal text fields (Rename r, Create Item n, Search, and Zip).
• Readline Shortcuts: Includes Ctrl+U (clear line) and Ctrl+W (delete word backwards).
• UTF-8 Codepoint Navigation: Codepoint-aware multi-byte Backspace, Delete, and arrow keys preventing UTF-8 character corruption.
• Terminal Resize Adaptation: Prompts automatically re-center and adapt dynamically when the terminal is resized (KEY_RESIZE).

✨ Dynamic Nerd Font Type & Extension Indicator (n & r)

• Unified Shortcut: Press n to create files and directories from a single hotkey (creates a file if name, or a folder if name/ ending with /).
• Real-time Extension & Type Confirmation: As you type into the centered prompt, the bottom-right corner dynamically switches both glyph and syntax accent color in real time:
  • Dynamic File Extensions: Generic file icon () dynamically switches to specific language glyphs as you type extensions (e.g. hello.c ➔  C icon, hello.cc/.cpp ➔  C++ icon, hello.py ➔  Python icon, hello.rs ➔  Rust icon, hello.go ➔  Go icon, hello.zig ➔  Zig icon, hello.json ➔ , hello.sh ➔ , hello.md ➔ , hello.zip ➔ , etc.).
  • Special Files & Configs: Recognizes files like Makefile (), Dockerfile (󰡨), .gitignore (), .bashrc/.zshrc (), etc.
  • Dynamic Folder Indicator: Switches instantly to folder icon ( / configured directory glyph) the moment / or \ is appended.
• Active Accent Coloring: Input dialog borders, headers, and dynamic type icons are uniformly styled with the active theme accent color (active_border / pin_border in theme.toml).
• Nested Path Creation & Smart Focus: Supports recursive paths (e.g., nested/sub/dir/ or sub/folder/file.txt), automatically selecting the newly created item in the listing.

⚡ Robust 12GB+ Directory Size Engine

• Non-throwing filesystem traversal engine that skips unreadable files or recursive symlink loops cleanly without cutting size calculation short on large multi-gigabyte directories.

🧩 Embedded Lua Plugin Engine

Fyzenor features an embedded Lua Plugin Engine (inspired by Yazi and Neovim), allowing you to create custom keybindings, interactive fast-jumps, status bar extensions, and custom file previewers without modifying C++ code!

Plugins are loaded automatically from ~/.config/fyzenor/plugins/*/init.lua on boot.

📦 Official Plugins Repository

Install all official plugins via single-command clone:

git clone https://github.com/Bimbok/fyzenor-plugins.git ~/.config/fyzenor/plugins

Included Official Plugins:

• Git Status & Staging (plugins/git/init.lua): Ctrl+B (Branch status summary), Ctrl+S (Smart stage/unstage toggle), Ctrl+K (Git diff stats).
• Zoxide Smart Jump (plugins/zoxide/init.lua): z / Alt+Z interactive modal jump prompt.
• JSON Custom Previewer (plugins/json_previewer/init.lua): Custom formatted previewer for .json files.

⚙️ External Configuration (config.toml)

Fyzenor uses an external configuration file located at ~/.config/fyzenor/config.toml (automatically created on first launch or during installation). It allows you to customize the program's general options, panel sizes, pane visibility rules, icon glyphs (Nerd Fonts), and file extension mappings.

Configuration Format

Here is the fully documented default structure of ~/.config/fyzenor/config.toml:

[general]
# Show hidden files by default on startup
show_hidden = false

# Default sorting mode: "name", "size" (descending), or "date" (descending)
sort_mode = "name"

# Default view mode: "columns" (Miller 3-column) or "grid" (2D thumbnail card grid)
view_mode = "columns"

# Enable or disable high-resolution media thumbnails in 2D Grid View
grid_thumbnails = true

[layout]
# Proportional width of the left parent/pinned column in normal mode (ratio between 0.0 and 1.0)
parent_width = 0.18

# Proportional width of the central files list column in normal mode
current_width = 0.32

# Set to true to hide the rightmost file preview pane by default on startup (toggleable via F3)
hide_preview = false

# Set to true to hide the parent directory pane by default on startup (toggleable via F4)
hide_parent = false

# Set to true to hide the pinned bookmarks pane by default on startup (toggleable via F6)
hide_pinned = false

[icons]
# Custom glyphs for directory and file indicators (Nerd Fonts recommended)
dir = " "
video = " "
image = " "
core = " "
frontend = "󰖟 "
config = " "
script = " "
docs = " "
font = " "
file = " "
music = " "
pin = " "
zip = "󰿺 "
link = "󰌹 "

[categories]
# Map specific file extensions to styling and icon categories
video = [".mp4", ".mkv", ".avi", ".mov", ".flv", ".wmv", ".webm", ".m4v", ".mpg", ".mpeg"]
image = [".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg", ".tiff", ".ico", ".psd", ".ai"]
frontend = [".js", ".jsx", ".ts", ".tsx", ".css", ".scss", ".sass", ".less", ".styl", ".vue", ".html", ".svelte", ".htm", ".astro", ".mjx", ".dart", ".swift"]
scripts = [".sh", ".bash", ".zsh", ".fish", ".ksh", ".command", ".pl", ".pm", ".t", ".awk", ".ps1", ".psm1", ".bat", ".cmd", ".vbs", ".wsf"]
config = [".json", ".json5", ".jsonc", ".xml", ".xsd", ".xsl", ".gpx", ".yaml", ".yml", ".toml", ".ini", ".conf", ".cfg", ".prefs", ".properties", ".lock", ".env", ".dockerfile", ".gitignore", ".gitconfig", ".gitattributes", ".gitmodules"]
documentation = [".md", ".markdown", ".txt", ".text", ".log", ".pdf", ".doc", ".docx", ".odt", ".rtf", ".ppt", ".pptx", ".odp", ".xls", ".xlsx", ".ods", ".csv"]
core = [".py", ".pyw", ".ipynb", ".pyc", ".pyd", ".rb", ".ru", ".gemspec", ".php", ".cpp", ".cxx", ".cc", ".hpp", ".hxx", ".ixx", ".c", ".h", ".rs", ".java", ".class", ".jar", ".war", ".go", ".lua", ".sql", ".db", ".sqlite", ".sqlite3", ".db3", ".mdb", ".accdb", ".cmake", ".make", ".diff", ".patch", ".kt", ".kts", ".cs", ".csx", ".scala", ".sc", ".hs", ".lhs", ".clj", ".cljs", ".cljc", ".edn", ".r", ".rmd", ".jl", ".fs", ".fsi", ".fsx"]
font = [".woff", ".woff2", ".ttf", ".eot", ".otf"]
audio = [".mp3", ".wav", ".flac", ".m4a", ".aac", ".ogg", ".wma", ".opus", ".mid", ".midi"]
archive = [".zip", ".tar", ".gz", ".tgz", ".7z", ".rar", ".xz", ".bz2", ".tbz2", ".lzma", ".cab"]

---

🎨 Customization & Theming

Fyzenor supports custom themes via ~/.config/fyzenor/theme.toml. The default theme is Catppuccin Mocha.

Configuration Format

Create ~/.config/fyzenor/theme.toml and define colors using hex codes inside the [colors] section:

[colors]
dir = "#89b4fa"
file = "#cdd6f4"
sel_bg = "#585b70"
media = "#f9e2af"
image = "#f5c2e7"
border = "#b4befe"
success = "#a6e3a1"
error = "#f38ba8"
multi = "#fab387"
pin_bg = "#cba6f7"
pin_border = "#89b4fa"
sec_sel_bg = "#313244"
code = "#a6e3a1"
archive = "#eba0ac"

Wallpaper-Based Theming (Matugen)

Instead of manually writing colors, you can use Matugen to generate a theme that matches your current wallpaper.

Step 1: Create the Matugen Template

Create ~/.config/matugen/templates/fyzenor-colors.template:

# Fyzenor Theme: Matugen Generated

[colors]
dir = "{{colors.primary.default.hex}}"
file = "{{colors.on_surface.default.hex}}"
sel_bg = "{{colors.surface_variant.default.hex}}"
media = "{{colors.tertiary.default.hex}}"
image = "{{colors.secondary.default.hex}}"
border = "{{colors.outline.default.hex}}"
success = "{{colors.primary_fixed.default.hex}}"
error = "{{colors.error.default.hex}}"
multi = "{{colors.tertiary_container.default.hex}}"
pin_bg = "{{colors.secondary_container.default.hex}}"
pin_border = "{{colors.primary.default.hex}}"
sec_sel_bg = "{{colors.surface_dim.default.hex}}"

Step 2: Update your Matugen Config

Add this block to your ~/.config/matugen/config.toml:

[templates.fyzenor]
input_path = "~/.config/matugen/templates/fyzenor-colors.template"
output_path = "~/.config/fyzenor/theme.toml"

Step 3: Generate the Colors

matugen image /path/to/your/wallpaper.jpg

---

🛠️ Custom Keyboard Macros (keys.toml)

You can map single-key shortcuts to run shell commands on currently highlighted or selected files.

Create ~/.config/fyzenor/keys.toml and specify key mappings inside the [macros] section:

[macros]
# $f - Expands to highlighted file path
# $s - Expands to space-separated selected paths (falls back to $f if none selected)
v = 'nvim "$f"'
g = 'git diff'
l = 'ls -la'

When a custom key is pressed inside the browser panel (e.g. v), Fyzenor suspends NCurses mode, executes the command directly inside the currently browsed directory in your interactive shell (giving you full access to standard I/O), waits for you to press Enter, and then returns to the file manager, reloading the directory.

---

🛠️ CLI Usage

Fyzenor supports the following command-line arguments:

fyzenor [options] [path]

Argument / Option	Description
[path]	Directory to open, or file to highlight and select on startup.
--chooser-file <file>	Write chosen files to this file upon exit (file chooser mode).
--cwd-file <file>	Write the final current working directory to this file on exit.
-v, --version	Display the current version of Fyzenor.
-h, --help	Show the help message and exit.

# Open Fyzenor at a specific directory
fyzenor ~/Projects

# Open Fyzenor hovering on a specific file
fyzenor src/main.cpp

# Use as a file chooser
fyzenor --chooser-file=/tmp/selected.txt

---

🔌 Neovim Integration (fyzenor.nvim)

Fyzenor integrates directly into Neovim as an ultra-fast floating file manager, file picker, and netrw replacement (modeled after yazi.nvim).

📦 Installation

Using lazy.nvim

{
  "Bimbok/fyzenor",
  branch = "beta",
  cmd = { "Fyzenor", "FyzenorToggle", "FyzenorCwd" },
  keys = {
    { "<leader>-", "<cmd>Fyzenor<cr>", desc = "Open Fyzenor at current file" },
    { "<leader>cw", "<cmd>FyzenorCwd<cr>", desc = "Open Fyzenor in Neovim CWD" },
  },
  opts = {
    -- Hijack netrw when opening directories (e.g. `nvim .` or `:edit dir/`)
    open_for_directories = true,
    -- Synchronize Neovim's current working directory with Fyzenor on close
    change_neovim_cwd_on_close = false,
    -- Floating window scaling factor (0.1 to 1.0)
    floating_window_scaling_factor = 0.9,
    -- Window border style ("rounded", "single", "double", "none")
    border = "rounded",
    -- Keymaps active inside the Fyzenor floating terminal
    keymaps = {
      open_file_in_vertical_split = "<c-v>",
      open_file_in_horizontal_split = "<c-x>",
      open_file_in_tab = "<c-t>",
      send_to_quickfix_list = "<c-q>",
      copy_relative_path_to_selected_files = "<c-y>",
      grep_in_directory = "<c-f>",
      show_help = "<f1>",
    },
  },
}

Using packer.nvim

use({
  "Bimbok/fyzenor",
  config = function()
    require("fyzenor").setup({
      open_for_directories = true,
    })
  end,
})

Using vim-plug

Plug 'Bimbok/fyzenor'

" In your init.lua / init.vim
lua require("fyzenor").setup()

🎮 Neovim Commands & Lua API

Command / Lua API	Description
:Fyzenor [path]	Opens Fyzenor focused on [path] (or current file/cwd).
:Fyzenor cwd	Opens Fyzenor directly in Neovim's working directory.
:FyzenorToggle [path]	Toggles the Fyzenor floating window.
:FyzenorCwd	Shortcut to open Fyzenor in CWD.
require("fyzenor").open()	Lua function to open Fyzenor programmatically.
require("fyzenor").toggle()	Lua function to toggle Fyzenor.

⌨️ Terminal Keybindings (Inside Floating Fyzenor)

Keybinding	Action
<Enter>	Choose selected file(s) and open in current window
<C-v>	Open selected file(s) in a vertical split
<C-x>	Open selected file(s) in a horizontal split
<C-t>	Open selected file(s) in a new tab
<C-q>	Send selected file(s) to Neovim's quickfix list
<C-y>	Copy relative path of selected file(s) to clipboard (+ register)
<C-f>	Live grep / search inside the browsed directory
C	Choose current working directory as selection
q	Cancel selection and close floating window
<F1>	Display floating keymap help modal

---

🏗️ Architecture

Fyzenor is structured as a compact terminal application with asynchronous jobs handling the expensive operations that would otherwise block UI updates.

fyzenor/
├── src/               # Core C++ source files (file_manager, utils, plugins)
├── install.sh         # Universal installer, updater, and manager
├── uninstall.sh       # Standalone uninstaller script
├── fyzenor.png        # Branding asset used in desktop entry and README
└── Sample/            # Showcase screenshots

How It Works

1. Navigation State: Tracks the current directory, parent context, selected entry, pins, and multi-selection state.
2. Async Preview Pipeline: Generates media previews and text previews without freezing the navigation loop.
3. Background Size Calculation: Directory sizes are resolved in the background and merged back into the UI.
4. Command Handling: Keybindings trigger file operations, pin management, sorting, preview refresh, and shell integration behavior.

System Flow

flowchart TD
    user[User]
    input[Keyboard Input]
    nav[Navigation State]
    jobs[Async Preview and Size Jobs]
    preview[Preview Renderer]
    ops[File Operations]
    tui[Terminal UI]

    user --> input
    input --> nav
    nav --> jobs
    nav --> ops
    jobs --> preview
    preview --> tui
    ops --> tui
    tui --> user

Loading

---

⌨️ Controls

Navigation

Key	Action
k or ↑	Move selection up
j or ↓	Move selection down
h or ← or BS	Go to parent directory / Clear search results
l or → or Enter	Open file / Enter directory
g	Go to top of list
G	Go to bottom of list
/	Search content (ripgrep)
f	Fuzzy Find files (internal)
w	Active Tasks manager overlay
Ctrl+O	Go back in directory navigation history
Ctrl+P	Go forward in directory navigation history
H	History Overlay (jump to recently visited directories)
Ctrl+E / Ctrl+Y	Scroll Preview Pane down / up without changing file selection
Mouse Wheel	Hover-Aware Pane Scrolling (hover middle pane to scroll files, hover preview to scroll content, hover pins to scroll bookmarks)

Note on Opening Files: Fyzenor automatically detects text and code files and opens them using your terminal-based editor, respecting $EDITOR, $VISUAL, nvim, nano, then vi. Media files are opened with mpv if available, and other files use your system's default opener.

File Operations

Key	Action
y	Yank (Copy) selected items to internal clipboard
x	Cut selected items
p	Paste items from clipboard
Y	Paste as Symlink (absolute symlinks of clipboard)
d or Delete	Move to Trash (deletes permanently if inside Trash Manager)
D	Delete permanently (skips Trash)
T	Toggle Trash Manager
u	Undo last move-to-trash action
r	Rename current item (acts as Restore if inside Trash Manager)
n	Create Item (name for file, name/ for folder, with dynamic extension/type Nerd Font icon)
z	Zip selected items into an archive
e	Extract archive (acts as Empty Trash if inside Trash Manager)
c	Copy Absolute Path to system clipboard
Ctrl-D	Drag Out selected/highlighted files using ripdrag or dragon
I	Visual Permissions & Ownership Editor (inspect/edit chmod/chown)

Selection, View & Pins

Key	Action
Space / v	Toggle selection (Space advances to next item, v stays on current)
a	Select All files in current directory
Esc	Clear all active selections
.	Toggle hidden files
s	Cycle sorting (Name $\rightarrow$ Size $\rightarrow$ Date Modified)
V / Shift+V	Toggle 2D Grid View Mode (switch between 3-column Miller mode and 2D visual thumbnail card grid)
U	Toggle Visual Disk Usage & Bar Graph Mode (ncdu / gdu view with live proportional meters)
P	Pin current directory
Tab	Toggle focus between Files and Pins (or switch active panes in Dual-Pane mode)
F2	Toggle Dual-Pane mode (split-screen side-by-side files lists)
F3	Toggle Preview Pane visibility (normal mode only)
F4	Toggle Parent Pane visibility (normal mode only)
F6	Toggle Bookmarks (Pinned) Pane visibility (normal mode only)
Ctrl+G	Open Lazygit (normal mode) or Grow active pane width (Dual-Pane mode)
Ctrl+B / Ctrl+H	Shrink active pane width (Dual-Pane mode only)
F5 or Ctrl+R	Refresh directory layout and clear size/preview caches
i	Show File Details (permissions, owner, size, times)
m	Show Devices & Mounts overlay (detect, mount, unmount USB drives & Android phones)
:	Execute Shell Command (suspend TUI / background &)
?	Show Interactive Keybindings Modal (spacious scrollable 2-column shortcut overlay)
q	Quit Fyzenor

Tab Controls

Key	Action
t	Create New Tab
W or Ctrl+W	Close Current Tab
[ or ]	Switch to Previous / Next Tab
1 - 9, 0	Switch directly to Tab 1 - 10 (0 maps to tab 10)

Pin Mode Controls

• j / k or ↑ / ↓: Navigate through your pins.
• Enter / l / →: Instantly jump to the pinned directory.
• d / Delete: Remove the selected pin.
• Tab: Switch focus back to the main file browser.

---

🎨 Visuals & Protocols

Kitty Graphics Protocol & Multi-Terminal Media Engine

Fyzenor incorporates a high-performance, asynchronous media preview engine built on the Kitty Graphics Protocol, delivering crisp image and video thumbnails without compromising navigation responsiveness:

• Zero-Flicker Synchronized Updates: Leverages DEC Mode 2026 (\033[?2026h / \033[?2026l) to batch terminal draw operations into single atomic frames. This completely eliminates cursor jumping and visual tearing across fast terminals like Kitty and Ghostty.
• Memory-Safe Texture Lifecycle: Uses targeted Kitty graphics commands (a=T,i=1) to swap media previews directly in-place, and explicit ID-based deletion (d=A) to prune stale textures from GPU memory. This prevents memory leaks and terminal freezes during rapid navigation in memory-strict emulators like WezTerm.
• Selective Cell Preservation: Intelligently preserves unaffected TUI regions (directory trees, breadcrumbs, status bars) while updating the preview viewport, delivering smooth 60fps-like browsing.
• Non-Blocking Worker Pipeline: Media thumbnails are extracted and scaled asynchronously in worker threads via ffmpeg, caching rendered frames in an LRU session cache for instantaneous recall.
• Tested Across Top Modern Emulators: Hardened and verified on Kitty, Ghostty, and WezTerm, with graceful fallback to file metadata and syntax-highlighted text previews on terminals without graphics protocol support.

Nerd Fonts

Icons are rendered using Nerd Fonts. Ensure your terminal is using a Nerd Font for icons to display correctly.

Syntax Highlighting

Fyzenor integrates with bat or batcat to preview code and text files with rich syntax highlighting. Highlighted files are parsed directly into standard ncurses colors via a custom ANSI escape parser.

󰩹 Trash, Tasks & Smart Copying

1. Multi-Partition Trash System

Fyzenor provides an in-built Freedesktop.org-compliant Trash manager:

• Asynchronous Execution: Trashing (d) runs entirely on background AsyncTask worker threads, ensuring that deleting large numbers of files (e.g. Select All -> d) never locks up or freezes the UI loop.
• Automatic Mount Detection: Trashing (d) automatically detects the mount point of the partition containing the file.
• Partition Bins: If the file is on your home partition, it moves to ~/.local/share/Trash. On separate partitions (like shared drives or USB mounts), it creates and moves the file to <mount_point>/.Trash-<uid> to avoid slow, redundant cross-device copies.
• External Drive Fallbacks: On read-only or unsupported filesystems (where local trash folders cannot be created), Fyzenor prompts: "Trash not supported. Delete permanently? (y/n)".
• Trash Manager (T): Displays a unified list of trashed items across all mounted partition trash bins, resolving original filenames/extensions and allowing bulk Restoring (r), permanent Deletion (d), or Emptying (e) of all trash folders in the background.

2. Play/Pause Task Manager (w)

Pressing w displays background worker queues (copying, moving, deleting, trashing, zipping, and extracting).

• C++ Worker Suspend: Pressing Space or p on a C++ task (like copy, delete, or trash) uses C++ condition variables to suspend the worker threads. They sleep at 0% CPU consumption until resumed.
• POSIX Subprocess Suspend: Pausing external operations (Zip/Extract) sends a SIGSTOP signal to suspend the child process, and SIGCONT to resume it.
• Safe Cancellation: Paused tasks can be safely killed (x / d), automatically waking up the threads/subprocesses first to ensure clean exits and prevent zombie processes.
• Throughput & Timing Metrics: Actively displays task execution durations (in seconds) and live transfer speeds (e.g. MB/s) for copying and moving operations.
• Completed Tasks History Log: Displays a split-pane log of recent completed, cancelled, or failed background operations. Clear the logs by pressing c.

3. Smart Copy Resumption (Delta Copying)

When performing a paste operation:

• Skipping: Files that already exist at the destination and match the source size are skipped instantly.
• Resumption: If a copy was cancelled or interrupted, Fyzenor opens the destination file, seeks to its current size, seeks to the same position in the source file, and resumes copying only the remaining bytes block-by-block. Symlinks are automatically deleted and replaced to avoid overwriting their target paths.

4. Visual Permissions & Ownership Editor (I)

Instead of typing commands in a shell command prompt, users can launch an interactive modal overlay by pressing I (Shift+i) on any highlighted file.

• Checkbox Permission Grid: Visual 3x3 checkbox matrix to view and toggle Read, Write, and Execute bits for Owner, Group, and Others.
• Ncurses Interactive Controls: Allows using Vim navigation keys (h/j/k/l or Arrows) and toggling with Space or Enter.
• Metadata Field Modifiers: Pressing Enter on the Owner or Group rows prompts the user to easily change the user/group IDs or usernames via POSIX chown.

5. Tab-Scoped Navigation History (Ctrl+O / Ctrl+P / H)

Fyzenor tracks navigation transitions (folder entries, parent traversal, pinned jumps, mount browsing) independently for each tab.

• Jump Navigation: Press Ctrl+O to jump back to the previously visited directory, and Ctrl+P to jump forward.
• Navigation History List (H): Press H to open a pop-up listing recently visited directory paths (newest first). Selecting a path and pressing Enter jumps directly to that folder and saves the jump to the back history stack.

---

🤝 Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Test locally.
5. Open a pull request with a clear description.

For detailed contribution Workflow, see CONTRIBUTING.md. Community participation is governed by CODE_OF_CONDUCT.md.

---

📞 Contact

• GitHub: Bimbok
• Issues: Open an issue

---

⚖️ License

Distributed under the MIT License. See LICENSE for more information.

✨ README Improvement Notes

📌 Formatting Enhancements Needed

• Improve heading hierarchy for better readability
• Ensure consistent spacing between sections
• Use proper Markdown formatting for code blocks and lists
• Align all installation and usage steps properly

🚀 Suggested Structure Upgrade

• Introduction
• Features
• Tech Stack
• Installation
• Usage
• Project Structure
• Contribution Guidelines
• License

🛠️ Documentation Improvements

• Add badges (optional): build, license, contributors
• Add screenshots for better UI understanding
• Standardize code blocks for commands

🎯 Goal

Improve onboarding experience for new contributors and users by making README more structured, readable, and professional