RTFM - Ruby Terminal File Manager

A feature-rich terminal file manager written in pure Ruby. Browse directories with syntax-highlighted previews, inline images, remote SSH/SFTP access, comprehensive undo system, OpenAI integration, and much more.

RTFM parses your LS_COLORS for consistent terminal theming and runs on any modern terminal emulator.

# Install
gem install rtfm-filemanager

# Run
rtfm

# Or start in specific directory
rtfm ~/Documents

# Use as file picker (tag files with t, quit with q)
rtfm --pick=/tmp/selected_files.txt

# Press ? for help

After first run, use r command to launch RTFM and exit into your current directory.

OpenAI File Analysis	Interactive AI Chat
Syntax Highlighting	System Information

• Key Features
• Installation
• Keyboard Reference
• Remote SSH/SFTP Browsing
• Configuration
• OpenAI Integration
• Plugins
• Image Display
• RTFM vs Ranger
• Documentation

• Comprehensive undo system - Undo delete, move, rename, copy, symlink, permissions, ownership
• Trash bin - Optional safe deletion with restore capability
• Bulk operations - Copy, move, delete multiple tagged items
• Bulk rename - Pattern-based renaming (regex, templates, case conversion)
• Permission management - Change permissions with undo support (755, rwxr-xr-x, +x, -w)
• Ownership management - Change user:group with undo support

• Syntax highlighting - File content with bat/batcat
• Inline images - w3m and Sixel protocols via termpix gem
• EXIF orientation - Correct display of rotated images
• Video thumbnails - ffmpegthumbnailer integration
• Archive preview - View contents of .zip, .tar, .gz, .rar, .7z files
• Document preview - PDF, LibreOffice, MS Office files
• LS_COLORS parsing - Consistent terminal color theming

• SSH/SFTP browsing - Navigate remote directories seamlessly
• Interactive SSH shell - Drop into shell sessions on remote hosts
• File transfer - Download and upload files
• Connection caching - Smart caching for performance

• Git integration - Status display for repositories
• Cryptographic hashing - Directory tree verification
• OpenAI integration - File descriptions and interactive chat
• Tab management - Multiple tabs with duplication and renaming
• File picker mode - Use RTFM as a file selector for other applications (--pick)
• Fuzzy search - fzf integration
• Navi integration - Interactive command cheatsheets

• Plugin system - Live enable/disable plugins with built-in manager (V key)
• Example plugins - Settings editor, git, bookmarks, notes, custom openers
• Ruby debug mode - Execute arbitrary Ruby in context
• Command history - Preserved across sessions

gem install rtfm-filemanager

sudo apt update
sudo apt install ruby-full x11-utils xdotool bat pandoc poppler-utils \
  odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick \
  ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full

gem install rtfm-filemanager

sudo pacman -Syu ruby bat pandoc poppler odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick ffmpegthumbnailer p7zip libreoffice-fresh
gem install rtfm-filemanager

Note: catppt is not available in official repos, but RTFM will fall back to using LibreOffice's soffice for .ppt files. For xls2csv, use an AUR helper:

yay -Syu perl-xls2csv

brew install ruby imagemagick w3m bat pandoc poppler

gem install rtfm-filemanager

Required:

• Ruby 2.7+
• rcurses gem (~> 6.0)
• termpix gem (~> 0.2)

Optional (for full functionality):

• ImageMagick - Image preview (identify, convert)
• w3m-img - w3m image protocol
• xdotool - Image redraw on workspace switching
• bat/batcat - Syntax highlighting
• fzf - Fuzzy file finding
• pandoc - Document conversion
• ffmpegthumbnailer - Video thumbnails
• ruby-openai - AI integration

For complete reference: man rtfm or press ? in RTFM

Permission formats: 755, rwxr-xr-x, rwx, +x, -w, +rw

Interactive mode example: :§htop - runs htop in full terminal

Access and manage files on remote servers directly from RTFM.

1. Press Ctrl-e
2. Enter connection string:

   user@server.com:/path/to/directory
   

# Basic SSH
user@server.com:/path

# Custom SSH key
-i ~/.ssh/custom-key user@server.com:/path

# SSH URI
ssh://user@server.com/path

# With comment
user@server.com:/path # Production server

Visual indicator: Red background when in remote mode

Press Enter on any archive file (.zip, .tar.gz, .tar.bz2, .tar.xz, .rar, .7z) to browse its contents as a virtual directory.

Visual indicator: Yellow-green background when in archive mode

Configuration stored in ~/.rtfm/conf

Tip: Install the Settings plugin for an interactive settings editor with live color preview. See Plugins.

# ~/.rtfm/conf

# Enable trash bin
@trash = true

# Toggle preview on/off
@preview = true

# Show/hide images
@showimage = true

# Show hidden files
@lsall = "-a"

# Show long file info
@lslong = true

# Pane width (2-7)
@width = 5

# Border style (0-3)
@border = 2

# OpenAI API key
@ai = "your-api-key-here"

# Directory bookmarks (persistent)
@marks = {"h" => "/home/user", "d" => "/home/user/Documents"}

# Command history (persistent)
@history = ["git status", "ls -la"]

# Interactive programs whitelist
@interactive = "htop,vim,emacs,nano"

# Top line background colors by path match
@topmatch = [["projects", 165], ["", 238]]

# Bottom pane
@bottomcolor = 238

# Command mode
@cmdcolor = 24

# Ruby mode
@rubycolor = 52

# OpenAI chat
@aicolor = 17

RTFM includes built-in AI features powered by OpenAI's API for intelligent file analysis and interactive assistance.

1. Get an API key:

   • Sign up at https://platform.openai.com/
   • Generate an API key from your account settings

2. Configure RTFM: Add your API key to ~/.rtfm/conf:

   @ai = "sk-your-actual-api-key-here"
   @aimodel = "gpt-4o-mini"  # Optional: default model
   @aicolor = 17             # Optional: chat pane background color

The ruby-openai gem is already included as a dependency when you install RTFM.

Get an intelligent summary of any file or directory:

• Files: Purpose, code review (for source files), library documentation lookup
• Directories: Overview of structure and contents
• Git-aware: Includes recent changes if in a git repository
• Smart analysis: Automatically includes preview content for context

Example uses:

• Understand unfamiliar codebases quickly
• Get code review suggestions (bugs, style, improvements)
• Learn what libraries/APIs are being used
• See git diff explanations in plain language

Start a conversational AI assistant specialized in:

• File and directory questions
• Shell command help and suggestions
• Terminal workflow assistance
• Programming and scripting guidance

The chat maintains context throughout your RTFM session, so follow-up questions work naturally.

# Model selection (in ~/.rtfm/conf)
@aimodel = "gpt-4o-mini"      # Fast, cost-effective (default)
@aimodel = "gpt-4o"           # More capable, higher cost
@aimodel = "gpt-4-turbo"      # Alternative high-end model

# Chat interface color
@aicolor = 17                 # Dark blue background (default)

• API calls cost money (typically $0.001-0.01 per request with gpt-4o-mini)
• File contents are sent to OpenAI when using I key
• No data is sent unless you explicitly press I or Ctrl-a
• Chat history persists only during your RTFM session

RTFM has a plugin system with live enable/disable. Plugins live in ~/.rtfm/plugins/ as .rb files and are auto-loaded on startup.

Press V to open the built-in plugin manager:

• See all available plugins with their status (ON/OFF)
• Press ENTER to toggle a plugin on or off (takes effect immediately)
• Press ? to view the plugin's built-in help text
• No restart required

RTFM ships with five example plugins in the examples/ directory. Copy any of them to ~/.rtfm/plugins/ to activate:

cp examples/settings.rb ~/.rtfm/plugins/
cp examples/git.rb ~/.rtfm/plugins/
cp examples/bookmarks.rb ~/.rtfm/plugins/
cp examples/notes.rb ~/.rtfm/plugins/
cp examples/opener.rb ~/.rtfm/plugins/
cp examples/diskusage.rb ~/.rtfm/plugins/
cp examples/dupes.rb ~/.rtfm/plugins/

A plugin is a simple Ruby file with metadata comments and KEYMAP bindings:

# @name: My Plugin
# @description: What it does
# @key: X

KEYMAP['X'] = :my_action

# Optional: register help text shown by ? in plugin manager
PLUGIN_HELP['My Plugin'] = <<~HELP
  This is the help text for my plugin.
  Shown when pressing ? in the plugin manager.
HELP

def my_action
  clear_image
  @pR.update = true
  @pR.say("Hello from my plugin!")
end

Plugins can also be defined in ~/.rtfm/keys.rb for personal bindings that don't need the enable/disable mechanism.

Custom file type previews are configured separately in ~/.rtfm/preview.rb:

# Syntax: ext1, ext2 = command with @s placeholder
txt, log = bat -n --color=always @s
md = pandoc @s -t plain
pdf = pdftotext -f 1 -l 4 @s -
json = jq . @s

# Capture command output as string
output = command("ls -la", timeout: 5)

# Run command interactively (full terminal)
shellexec("grep -r pattern .")

# Read a keypress
chr = getchr

# Clear any displayed image
clear_image

# Text formatting
"text".fg(112)   # foreground color (0-255)
"text".bg(236)   # background color
"text".b         # bold
"text".u         # underline
"text".r         # reverse

RTFM uses the termpix gem for modern multi-protocol image display.

• EXIF orientation - Phone photos display correctly
• Auto-detection - Best protocol for your terminal
• Aspect ratio - Images never stretched
• Toggle - Press _ to toggle image preview
• Copy to clipboard - Press Ctrl-y on image

Best image experience with: kitty, urxvt, xterm, mlterm, foot

Philosophy:

• Ranger: Minimalistic, "do one thing well"
• RTFM: Feature-packed, "jam packed with features"

Best for:

• RTFM: Power users wanting SSH workflows, undo, AI integration, maximum features
• Ranger: Users wanting clean, minimal, well-documented VIM-style navigation

• Man page: man rtfm
• Interactive help: Press ? in RTFM
• GitHub: https://github.com/isene/RTFM
• Changelog: See CHANGELOG.md
• Issues/Bugs: https://github.com/isene/RTFM/issues

• Getting Started - Installation, first run, basic operations
• Configuration Guide - Complete settings reference
• Remote Browsing - SSH/SFTP workflows
• Plugin Development - Extend RTFM with custom handlers

Keyboard Cheat Sheet:

• Plugin system with live enable/disable - Plugins in ~/.rtfm/plugins/ are auto-loaded on startup. Toggle them on and off at runtime with the plugin manager (V key), no restart needed. Each plugin can register help text viewable with ?.
• Seven example plugins - Settings editor, git operations, directory bookmarks, file notes, custom file openers, disk usage analyzer, and duplicate file finder. Copy from examples/ to ~/.rtfm/plugins/ to use.
• Trash browser (D key) - Browse trash contents with timestamps and original paths. Restore files to their original location, permanently delete individual items, or empty all trash.

• File picker mode - rtfm --pick=/path/to/output.txt launches RTFM as a file selector. Browse and tag files normally with t, then quit with q. Tagged file paths are written one per line to the output file. Enables integration with email clients, upload tools, and other applications that need a file selection dialog.

• Modern image display with termpix gem (Sixel + w3m protocols)
• Performance optimizations for large images
• UTF-16 file support for opening in $EDITOR
• Image clipboard copy (Ctrl-y)
• Persistent selection after operations

Batch operations now use consistent "tagged OR selected" logic:

• Tagged items exist → operate ONLY on tagged
• No tagged items → operate on selected

Migration: Explicitly tag selected item with t if you want it included.

See CHANGELOG.md for complete version history.

RTFM is a two-pane file manager with enhanced tab support:

• Left pane: Directory/file list with navigation
• Right pane: Preview, info, command output
• Top bar: Current path and file metadata
• Bottom bar: Status, prompts, commands
• Tab indicator: [2/5] shows current tab position

Tab Features:

• Multiple tabs for multi-directory management
• Duplicate tabs (}) to copy directory context
• Rename tabs ({) for organization
• Quick switch with number keys (1-9)

Enhanced UX:

• VIM-style navigation (hjkl)
• Arrow key support
• Persistent bookmarks and tagged items
• Command history across sessions
• Comprehensive undo for safety

On first launch, RTFM:

1. Shows welcome message
2. Adds r function to your shell (~/.bashrc, ~/.zshrc)
3. Creates ~/.rtfm/ directory
4. Generates plugin templates

The r function lets you:

• Launch RTFM with single key
• Exit into RTFM's current directory (not launch directory)

Workflow:

r              # Launch RTFM
# Navigate to desired directory
q              # Exit RTFM
pwd            # You're in RTFM's last directory!
r              # Back into RTFM

Created to solve a specific problem: file managers should parse LS_COLORS natively instead of requiring separate themes.

The Origin Story:

While working on a complete LS_COLORS setup, I realized creating a matching ranger theme was redundant. File managers should respect terminal colors by default.

This became RTFM - a file manager that parses LS_COLORS automatically.

Why Rewrite?

The old curses library was clumsy. So I created rcurses - a modern, pure Ruby curses implementation. From v5 onwards, RTFM runs on rcurses, providing:

• Better stability
• Cleaner code
• More features
• Active development

Bug reports and feature requests welcome at: https://github.com/isene/RTFM/issues

Ruby Debug Mode: Press @ to enter Ruby REPL mode. Execute arbitrary Ruby code:

# Examples:
puts @selected        # Show current selection
puts @tagged.inspect  # Show tagged items
puts @marks          # Show bookmarks

Plugin Development: See ~/.rtfm/plugins/ directory for templates and examples.

Contributing: This is a personal project built for my needs. Cool feature requests may be included. Code contributions welcome via pull requests.

Geir Isene

• Email: g@isene.com
• Web: https://isene.com
• GitHub: https://github.com/isene

Unlicense - Public Domain

Permission granted to use, copy, modify, distribute, and sell this software for any purpose without restriction.

• rcurses - Pure Ruby curses library
• termpix - Terminal image display gem
• ranger - Python-based file manager
• LS_COLORS - Comprehensive terminal color setup

Stay Amazing ✓