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

# 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
• Fuzzy search - fzf integration
• Navi integration - Interactive command cheatsheets

• Plugin architecture - Custom preview handlers and key bindings
• Ruby debug mode - Execute arbitrary Ruby in context
• Command history - Preserved across sessions
• Extensible - Clean plugin API

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

Configuration stored in ~/.rtfm/conf

# ~/.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 supports two types of plugins in ~/.rtfm/plugins/:

Add custom file type previews:

# ~/.rtfm/plugins/preview.rb

# Syntax: ext1, ext2 = command with @s placeholder
# @s is replaced with shell-escaped filename

# Examples:
txt, log = bat -n --color=always @s
md = pandoc @s -t plain
pdf = pdftotext -f 1 -l 4 @s -
json = jq . @s

Add or override key bindings:

# ~/.rtfm/plugins/keys.rb

# Add new key binding
KEYMAP['Z'] = :my_custom_action

def my_custom_action(_chr)
  @pB.say("Custom action triggered!")
  # Use @pL, @pR, @selected, etc.
end

# Git commit shortcut example
KEYMAP['C-G'] = :git_commit

def git_commit
  message = @pCmd.ask('Commit message: ', '')
  shellexec("git add . && git commit -m '#{message}' && git push")
end

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

# Run command, show errors
shell("mv file1 file2", background: false)

# Run and show both stdout/stderr in right pane
shellexec("grep -r pattern .")

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: urxvt, xterm, mlterm, Eterm

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:

• 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 ✓