xefm 1.0.1

XeFM — a dual-pane file manager for the desktop and the terminal

XeFM — a dual-pane file manager for the desktop and the terminal

XeFM — short for Xenolith File Manager — is a powerful file manager that runs as a native desktop application on Windows and macOS, and in the terminal on all platforms — Windows, macOS, and Linux. Navigate your filesystem with keyboard shortcuts in a clean, intuitive dual-pane interface with comprehensive file operations, rich built-in viewers, themeable visual effects, and professional-grade features.

Key Features

• Cross-platform - Native desktop app on Windows and macOS; terminal (TUI) app on Windows, macOS, and Linux
• Dual-pane interface with independent navigation and cross-pane operations
• Archive browsing - Navigate ZIP, TAR, and compressed archives as virtual directories
• SFTP support - Browse and manage remote servers via SSH with optimized performance
• AWS S3 support for cloud storage operations
• Advanced search with real-time filtering and background processing
• Multi-selection with bulk operations and progress tracking
• Rich built-in viewers - Syntax-highlighted text, images, Markdown, JSON, and CSV/TSV
• Themes & visual effects - A dozen built-in themes; desktop mode adds GPU background animations, CRT/phosphor screen effects, and text-reveal animations
• External program integration with configurable launchers
• Customizable - Fully configurable key bindings and settings

Quick Start

Installation

Want the desktop app? The easiest way to run XeFM in desktop mode is to download and install a prebuilt application package — a self-contained XeFM.exe folder on Windows or a native .app on macOS, with Python and every dependency bundled in (no source checkout, no virtualenv). These packages are not yet uploaded to GitHub Releases — until then, use the from-source setup below (which also covers terminal mode on Windows, macOS, and Linux).

1. Install Python 3.10 or later. On macOS, Homebrew is the easiest route:

   brew install python@3.14
   

2. Clone XeFM:

   git clone https://github.com/shimomut/xefm.git
   cd xefm
   

3. Create the environment and run:

   make venv        # creates .venv using the newest python3 in PATH
   make run         # launch XeFM
   

   make venv creates and populates .venv/, and every other make target runs through that interpreter — so you never need to activate it yourself.

   Prefer to manage the environment yourself? Create and activate a virtualenv first, then install the dependencies:

   python3 -m venv .venv
   source .venv/bin/activate         # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   python3 -m xefm
   

   No pip install of XeFM itself is needed to run from a checkout: python3 -m puts the working directory on the import path, and the xefm package sits at the repo root. Run pip install -e . only if you want the xefm command available from other directories.

   Desktop Mode runs on Windows and macOS. The Windows GUI backend is pure Python and needs nothing extra; the macOS one uses PyObjC, installed automatically by requirements.txt. Just pick the backend:

   python3 -m xefm --backend gui   # native desktop window on Windows or macOS
   

Essential Controls

• Navigate: ↑↓ to move up/down, ←→ to switch panes/navigate directories
• Enter archives: Press Enter on .zip, .tar, .tar.gz files to browse contents
• Select: Space to select/deselect files, A for all files, Shift-A for all items
• File operations: C (copy), M (move), K (delete), R (rename)
• Help: ? for comprehensive help dialog
• Quit: Q to exit

Help System

Press ? to open the comprehensive help dialog with all key bindings and features organized by category. The help dialog is your quick reference guide - no need to memorize all shortcuts!

Documentation

For comprehensive information about XeFM's features and usage:

User Documentation

• Complete User Guide - Comprehensive guide covering all features, configuration, and usage
• Configuration - Complete configuration reference and customization guide
• Desktop Mode - Native Windows / macOS desktop app setup and options
• Color Schemes & Visual Effects - Themes, themeable GPU background scenes, and screen effects
• Image Viewer - Built-in zoom / pan image viewer
• Markdown Viewer & JSON / CSV Viewers - Rendered structured-file views
• SFTP Support - Remote server access via SSH with file operations and search
• AWS S3 Support - Cloud storage integration and S3 bucket management
• Archives - Create, extract, and browse archives as directories
• Search Animation - Advanced search features and visual feedback

Developer Documentation

• Path Polymorphism System - Storage-agnostic architecture and extensibility
• Navigation System - Core navigation implementation
• External Programs - Program integration system

Key Features Overview

All key bindings are fully customizable through the configuration system. For complete key binding reference, press ? in XeFM or see the User Guide.

Core Operations

• Navigation: Arrow keys, Tab to switch panes, Enter to open directories/files/archives
• Archive Browsing: Press Enter on .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz files to browse as virtual directories
• File Operations: Copy (C), Move (M), Delete (K), Rename (R)
• Selection: Space to select files, A for all files, Shift-A for all items
• Search: F for incremental search, Shift-F for filename search, Shift-G for content search
• Archives: P to create archives, U to extract, Enter to browse contents
• File Viewers: V to view the selected file — text (syntax-highlighted), images, Markdown, JSON, and CSV/TSV (works inside archives); M toggles rendered/raw in the viewer

Advanced Features

• Favorite Directories: J for quick access to bookmarked locations
• External Programs: X for custom program integration
• Sub-shell Mode: Shift-X to enter shell with XeFM environment variables
• Themes: T to cycle themes; more display options under Z (view options) and Shift-Z (settings)
• Configuration: Shift-Z for settings menu (Z opens view options)
• SFTP Support: Navigate remote servers using ssh://hostname/path syntax
• AWS S3 Support: Navigate S3 buckets using s3://bucket/path syntax

For comprehensive SFTP setup and usage, see the SFTP Support Feature Guide.

For comprehensive S3 setup and usage, see the AWS S3 Support Feature Guide.

Archive Virtual Directory Browsing

XeFM lets you browse archive files as if they were regular directories - no extraction needed!

Supported formats: .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz

How to use:

1. Navigate to any archive file
2. Press Enter to browse its contents
3. Navigate directories inside the archive with arrow keys
4. Press Enter on files to view them
5. Copy files out with C (or your copy key)
6. Search within archives with Alt+F7
7. Press Backspace to exit the archive

What you can do:

• Browse nested directories within archives
• View text files with syntax highlighting
• Copy files and directories from archives to local/S3
• Search for files by name or content
• Select multiple files for batch operations
• Sort by name, size, date, or extension

See Archive Feature for complete documentation.

Built-in File Viewers

Press V (or Enter) to view the selected file. XeFM picks the right viewer for the file type — all of them work seamlessly on local files, inside archives, and on remote SFTP / S3 paths without extraction or download.

Text viewer

A powerful text viewer with syntax highlighting for 20+ file formats.

• Syntax highlighting for Python, JavaScript, JSON, Markdown, YAML, and more
• Line numbers, horizontal scrolling, line wrapping (W), and in-file search
• Multiple encoding support (UTF-8, Latin-1, CP1252)

Enhanced highlighting: pygments (installed via requirements.txt) enables full syntax support.

Rich viewers — Markdown, JSON, CSV/TSV

For structured files, the viewer offers a rendered view in addition to the raw text. Press M inside the viewer to toggle between the formatted and raw views.

Markdown	JSON / JSONL	CSV / TSV
Rendered headings, lists, code, and links	Collapsible, syntax-colored tree (.json, .jsonl, .ndjson)	Column-aligned table grid (.csv, .tsv)

Image viewer

A modal image viewer with zoom, pan, and prev/next navigation through the sibling images in the current pane.

• Supports PNG, JPEG, GIF, BMP, WebP, TIFF, ICO, and more (via Pillow)
• Renders inline in graphics-capable terminals (iTerm2, kitty, sixel) and in desktop mode; falls back to a metadata card (format / dimensions / size) elsewhere
• Zoom with + / -, pan with the arrow keys or a mouse drag, step through images with prev/next

Image decoding needs pillow (installed via requirements.txt).

Themes & Visual Effects

XeFM ships a dozen built-in themes. Press T to cycle to the next theme, or pick one from the View → Theme menu — your choice is remembered across restarts. Define your own in ~/.xefm/config.py and they appear in the picker alongside the built-ins.

Dark+	Monokai	Dracula
Nord	Solarized	Gruvbox Dark
Light+	Solarized Light	Sci-Fi
Cyber	Segment LCD	Shinagawa

The default config also includes a Phosphor sample theme — a monochrome phosphor-green CRT terminal — as a starting point for your own.

Visual effects (desktop mode)

In desktop mode (--backend gui), a theme can carry visual effects that the GPU renders behind and over the interface. Terminal mode simply shows the theme's colors and ignores these.

• Background animations — a slow, on-palette scene drawn behind the panes, rendered as a GPU fragment shader: starfield, rain, hologram, wave, grid, constellation, and datastream.
• Screen post-effects — a full-frame CRT / phosphor look composited over the UI: bloom, glow, scanlines, vignette, and drop shadows.
• Text-reveal animations — filenames and labels arrive rather than appear, decoding or typing into place on a directory change (used by Sci-Fi and Cyber).
• Translucent surfaces — panels and chrome can sit at reduced opacity so the animated background reads through.

Effects are pure theme data — each is a combination of parameters attached to a theme, so a custom theme can mix and match them without any application code.

Sub-shell Mode

Press Shift-X to temporarily suspend XeFM and enter a shell with environment variables providing access to current directories and selected files:

• XEFM_LEFT_DIR, XEFM_RIGHT_DIR - Directory paths for each pane
• XEFM_THIS_DIR, XEFM_OTHER_DIR - Current and other pane directories
• XEFM_LEFT_SELECTED, XEFM_RIGHT_SELECTED - Selected files in each pane
• XEFM_ACTIVE - Set to '1' to indicate XeFM sub-shell mode

Type exit to return to XeFM.

Advanced Features

• Native Desktop App: Run in a real window on Windows and macOS (--backend gui) with GPU rendering, or in any terminal — same keyboard-driven interface
• Archive Virtual Directories: Browse ZIP, TAR, and compressed archives as if they were directories - navigate, search, view files, and copy contents without extraction
• SFTP Support: Access remote servers via SSH with full file operations, search, and optimized performance through connection multiplexing and bulk operations
• AWS S3 Support: Navigate and manage S3 buckets with seamless local/remote operations
• Rich Viewers: Built-in viewers for text (syntax-highlighted), images (zoom/pan), Markdown, JSON, and CSV/TSV — plus text and directory diff viewers
• Themes & Effects: A dozen built-in themes with GPU background animations, CRT/phosphor screen effects, and text-reveal animations in desktop mode
• Batch Rename: Regex-based renaming with capture groups and macros
• Threaded Search: Non-blocking filename and content search with progress tracking (works inside archives and on remote servers)
• Pane Management: Resizable layout, directory sync, state persistence
• External Integration: VSCode, Beyond Compare, and custom program support

For detailed information on all features, see the User Guide.

Command Line Options

# Run in terminal mode (default)
python3 -m xefm

# Run in desktop mode (native window on Windows or macOS)
python3 -m xefm --backend gui

# Specify startup directories
python3 -m xefm --left /path/to/projects --right /path/to/documents

# Combined usage - desktop mode with custom directories
python3 -m xefm --backend gui --left ./src --right ./test

# Help and version
python3 -m xefm --help
python3 -m xefm --version

The full flag set is just --backend {tui,curses,gui,macos,windows}, --left DIR, --right DIR, --version, and --help.

Backend Selection

XeFM supports two rendering backends, chosen with --backend:

• Terminal Mode (--backend tui, alias curses): traditional terminal interface, works on all platforms (Windows, macOS, Linux) — the default
• Desktop Mode (--backend gui): native desktop window on Windows (Direct2D/DirectWrite) or macOS (CoreGraphics, via PyObjC). The gui alias resolves to the right backend for the current platform; windows / macos name them explicitly.

Desktop mode provides:

• Native window with resizing and full-screen support
• Customizable fonts (MONO_FONT_NAME / UI_FONT_NAME / FONT_SIZE)
• Window size and position remembered automatically across runs
• Better color accuracy with true RGB colors, plus GPU-rendered theme background animations and screen effects

See the Desktop Mode Guide for detailed desktop mode configuration.

Installation

Requirements

Terminal Mode (all platforms — Windows, macOS, Linux):

• Python 3.10+ with curses library (built-in on macOS/Linux, 3.14 supported)
• Windows: pip install windows-curses (installed automatically via requirements.txt)
• Terminal with curses support (Linux is terminal-mode only — desktop mode is Windows/macOS)

Desktop Mode (Windows or macOS):

• Python 3.10+ (3.14 supported)
• Windows: 10 or later — the GUI backend is pure Python (Direct2D/DirectWrite), no extra dependency to install
• macOS: 10.13 (High Sierra) or later — PyObjC (installed automatically via requirements.txt)

Dependencies

requirements.txt is the single source of truth and is installed in one shot:

pip install -r requirements.txt

It pulls in:

• puikit — the UI / rendering layer behind both the desktop and terminal modes
• pygments — enhanced syntax highlighting (20+ file formats)
• pillow — the built-in image viewer (decode / crop / scale; also enables inline terminal images)
• boto3 — AWS S3 support (cloud storage operations)
• watchdog — automatic directory-listing reload on file changes
• pyobjc — macOS desktop mode (selected automatically on macOS)
• windows-curses — terminal-mode curses support on Windows (selected automatically on Windows)

The last two use environment markers, so the platform-specific dependency for the machine you are on is installed for you. There is no [macos] extra to request. (The Windows desktop backend itself is pure Python and needs no build step.)

Installation Options

Option 1: Run Directly (No Installation)

# Create and activate a virtualenv
python3 -m venv .venv
source .venv/bin/activate         # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run from the repo root — `python3 -m` puts it on the import path, and the
# `xefm` package lives there, so nothing else needs installing.

# Terminal mode (all platforms)
python3 -m xefm

# Desktop mode (native window on Windows or macOS)
python3 -m xefm --backend gui

Option 2: Install as Package

# Install from source directory
cd xefm
pip install .

# Run from anywhere (installs a `xefm` console command)
xefm                # Terminal mode
xefm --backend gui  # Desktop mode (Windows / macOS)

Option 3: Development Installation

# Install in editable mode (changes reflected immediately)
cd xefm
pip install -e .

# Run from anywhere
xefm

Configuration

XeFM is highly configurable through ~/.xefm/config.py. Access configuration via the Settings menu (Shift-Z key) or edit manually.

Key areas:

• Themes, color schemes, and visual effects (including custom themes)
• Key bindings (fully customizable)
• External programs, file associations, and text editor
• Favorite directories and startup paths
• Performance and behavior settings

For detailed configuration options, see the Configuration Feature Guide and the User Guide.

Project Structure

xefm/
├── xefm/          # The `xefm` package — everything the app ships
│   ├── app.py     # The application (XeFMApp + top-level UI)
│   ├── __main__.py # `python -m xefm` entry point
│   ├── *.py       # Business logic, imported as `xefm.config`, `xefm.path`, …
│   └── tools/     # External programs for end users
├── tools/         # Development tools and utilities
├── test/          # Test files (1000+ passing tests)
└── doc/           # User documentation
    └── dev/       # Developer documentation

Troubleshooting

Installation Issues:

• Ensure Python 3.10+ is installed
• Check terminal compatibility with curses library (terminal mode)
• PyObjC (desktop mode) installs automatically on macOS via pip install -r requirements.txt

Desktop Mode Issues:

• Desktop mode runs on Windows and macOS; on other platforms use terminal mode
• On macOS, if PyObjC is missing XeFM automatically falls back to terminal mode
• Check console output for backend initialization messages
• See Desktop Mode Guide for detailed setup

Performance Issues:

• Install pygments for better text viewer performance
• Check available memory for large directory operations
• First access to large archives may be slow while structure is cached
• Desktop mode provides better performance with GPU acceleration

Archive Issues:

• Verify archive file is not corrupted
• Ensure you have read permissions for the archive
• Check supported formats: .zip, .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz
• Archives are read-only - use copy operations to extract files

For detailed troubleshooting, see the User Guide.

Contact Author

Have questions, suggestions, or found a bug? Get in touch:

• GitHub Repository: https://github.com/shimomut/xefm
• GitHub Issues: Report bugs or request features
• Author's X (Twitter): @smmrtmnr

We welcome feedback and contributions to make XeFM even better!

License

MIT License - see LICENSE file for details.

Support

• Issues: Create an issue on the project repository
• Documentation: Review files in doc/ and doc/dev/ directories
• User Guide: See XEFM_USER_GUIDE.md for comprehensive information