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 helpAfter 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 (
Vkey) - 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-filemanagersudo 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-filemanagersudo pacman -Syu ruby bat pandoc poppler odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick ffmpegthumbnailer p7zip libreoffice-fresh
gem install rtfm-filemanagerNote: 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-filemanagerRequired:
- 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
| Key | Action |
|---|---|
? |
Show help |
q |
Quit (save config) |
Q |
Quit (don't save) |
r |
Refresh display |
V |
Plugin manager |
| Key | Action |
|---|---|
j / ↓ |
Move down |
k / ↑ |
Move up |
h / ← |
Parent directory |
l / → / ENTER |
Enter directory / open file |
HOME / END |
First / last item |
PgUp / PgDn |
Page up / down |
| Key | Action |
|---|---|
m + letter |
Set bookmark |
' + letter |
Jump to bookmark |
~ |
Jump to home |
> |
Follow symlink |
Ctrl-r |
Recent files/directories |
Ctrl-e |
Toggle remote SSH mode |
| Key | Action |
|---|---|
t |
Tag/untag item |
Ctrl-t |
Tag by pattern |
T |
Show tagged items |
u |
Untag all |
| Key | Action |
|---|---|
p |
Copy tagged items here |
P |
Move tagged items here |
s |
Create symlinks |
c |
Rename item |
E |
Bulk rename (patterns) |
d |
Delete (→ trash if enabled) |
D |
Trash browser (browse, restore, delete) |
Ctrl-d |
Toggle trash on/off |
U |
Undo last operation |
| Key | Action |
|---|---|
Ctrl-p |
Change permissions (with undo) |
Ctrl-o |
Change ownership (with undo) |
Permission formats: 755, rwxr-xr-x, rwx, +x, -w, +rw
| Key | Action |
|---|---|
f |
Filter by extension |
F |
Filter by regex |
/ |
Search and highlight |
n / N |
Next / previous match |
g |
Grep content |
L |
Locate files |
Ctrl-l |
Fuzzy find (fzf) |
| Key | Action |
|---|---|
- |
Toggle preview on/off |
_ |
Toggle image preview |
b |
Toggle syntax highlighting |
w |
Change pane width |
B |
Cycle borders |
a |
Show/hide hidden files |
A |
Toggle long info (ls -l) |
o |
Change sort order |
i |
Invert sort |
| Key | Action |
|---|---|
y |
Copy path (primary selection) |
Y |
Copy path (clipboard) |
Ctrl-y |
Copy image/text to clipboard |
| Key | Action |
|---|---|
G |
Git status |
H |
Directory hash |
I |
OpenAI file description |
Ctrl-a |
OpenAI chat |
S |
System information |
X |
Compare two files |
e |
File properties |
| Key | Action |
|---|---|
] |
New tab |
[ |
Close tab |
J / K |
Previous / next tab |
} |
Duplicate tab |
{ |
Rename tab |
1-9 |
Switch to tab # |
| Key | Action |
|---|---|
: |
Execute shell command |
; |
Command history |
@ |
Ruby debug mode |
§ |
Force interactive mode (prefix) |
+ |
Whitelist program as interactive |
Interactive mode example: :§htop - runs htop in full terminal
Access and manage files on remote servers directly from RTFM.
- Press
Ctrl-e - 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| Key | Action |
|---|---|
← / h |
Parent directory |
→ / ENTER |
Enter dir / show file info |
D |
Download file |
u |
Upload tagged files |
s |
Open SSH shell |
Ctrl-e |
Exit remote mode |
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.
| Key | Action |
|---|---|
d |
Delete entry from archive |
D |
Extract entry to origin directory |
p |
Add pre-tagged local files into archive |
t |
Tag/untag for bulk operations |
LEFT |
Parent directory / exit archive |
Visual indicator: Yellow-green background when in archive mode
Configuration stored in ~/.rtfm/conf
| Action | Command |
|---|---|
| View config | Press C (or interactive editor with Settings plugin) |
| Save config | Press W |
| Reload config | Press R |
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 = 17RTFM includes built-in AI features powered by OpenAI's API for intelligent file analysis and interactive assistance.
-
Get an API key:
- Sign up at https://platform.openai.com/
- Generate an API key from your account settings
-
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
Ikey - No data is sent unless you explicitly press
IorCtrl-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
ENTERto 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/| Plugin | Key | Description |
|---|---|---|
| Settings | C |
Interactive editor for settings without dedicated keys (colors, trash, interactive programs, OpenAI config). Color changes apply in real-time. Overrides the default config viewer |
| Git | Ctrl-G |
Git operations menu: status, diff, commit+push, log. Output shown in right pane |
| Bookmarks | F6 |
Unlimited directory bookmarks with fuzzy filtering. Add, delete, and jump to bookmarked directories. Complements the built-in single-letter marks (m/') |
| Notes | F5 |
Attach text notes to any file or directory. View, edit, or delete notes. Stored in ~/.rtfm/notes/ |
| Opener | RIGHT/l |
Custom file openers by extension. Configure a hash of extension-to-command mappings (e.g., .hl files open in hyperlist) |
| Disk Usage | S |
Interactive disk usage analyzer. Extends system info with a browseable size-sorted directory view with visual bars |
| Dupes | F7 |
Find duplicate files by content hash. Two-pass scan (size then SHA256) with in-place deletion of duplicates |
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!")
endPlugins 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| Variable | Description |
|---|---|
@pT |
Top pane (info bar) |
@pL |
Left pane (file list) |
@pR |
Right pane (preview) |
@pB |
Bottom pane (status) |
@pCmd |
Command prompt (use .ask(prompt, default) for input) |
@selected |
Currently selected file/dir |
@tagged |
Array of tagged items |
@external_program_running |
Set true when launching TUI programs |
PLUGIN_HELP |
Hash to register help text (keyed by plugin name) |
# 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 # reverseRTFM uses the termpix gem for modern multi-protocol image display.
| Terminal | Protocol | Status |
|---|---|---|
| urxvt | w3m | ✓ Perfect |
| xterm | Sixel | ✓ Perfect |
| mlterm | Sixel | ✓ Perfect |
| kitty | Kitty | ✓ Perfect |
| foot | Sixel | ✓ Perfect |
- 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-yon image
Best image experience with: kitty, urxvt, xterm, mlterm, foot
| Feature | RTFM | Ranger |
|---|---|---|
| Language | Pure Ruby | Python |
| Size | ~6K lines (single file) | ~22K lines (modular) |
| License | Unlicense (public domain) | GPL v3 |
| LS_COLORS | Native parsing | Requires theming |
| Remote SSH/SFTP | ✓ Built-in | ✗ |
| Undo System | ✓ Comprehensive | Limited |
| Trash Bin | ✓ With restore | ✗ |
| OpenAI Integration | ✓ | ✗ |
| Permission/Ownership Undo | ✓ | ✗ |
| Image Protocols | Sixel + w3m | Various (ueberzug, kitty) |
| Tab Management | ✓ Enhanced | ✓ Basic |
| Bulk Rename | ✓ Patterns | ✓ |
| Plugin System | Ruby-based | Python-based |
| Community | Small | Large (16.6k stars) |
| Documentation | Growing | Extensive |
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 (Vkey), 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 (
Dkey) - 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.txtlaunches RTFM as a file selector. Browse and tag files normally witht, then quit withq. 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:
- Shows welcome message
- Adds
rfunction to your shell (~/.bashrc, ~/.zshrc) - Creates
~/.rtfm/directory - 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 RTFMCreated 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 bookmarksPlugin 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 ✓