tfx

Terminal-inspired interface File eXplorer
Pronunciation: Tafix
Version: 0.9.10

English | 日本語

tfx is a macOS file manager with a terminal-inspired interface and keyboard-first workflow. It combines a folder tree, split file panes, rich previews, drag and drop, and terminal app integration.

Screenshot

Features

• Terminal-style file list UI
• Single folder tree rooted at /
• Persistent pinned folders section
• Home, Documents, and Downloads are pinned by default on first launch
• Drag reordering for pinned folders
• Toggleable folder tree (toolbar, View menu, or cmd+option+f)
• Single-pane and equal-width split-pane modes
• Per-pane folder tabs
• Drag and drop between left and right file panes
• Option-drag copies files; normal drag moves files
• Visual highlighting for the active view
• .. row for parent-folder navigation
• Backspace parent-folder navigation
• Clickable breadcrumb path navigation
• PDF, video, Markdown, and Quick Look previews
• Toggle between rendered and source view for Markdown, HTML, CSV, and JSON previews
• CSV / TSV preview as a scrollable table; JSON preview as pretty-printed text
• Plain-text preview for TOML, YAML, INI, log, and similar config formats
• Compact preview metadata for selected files and folders
• Toggleable preview pane
• Browse zip archives without extracting them
• Copy files from browsed zip archives
• Open a terminal app at the current folder
• Built-in command terminal pane that starts in the active folder and accepts file/folder drops onto the terminal to insert shell-quoted paths. The shell session is kept alive while the pane is hidden — re-opening returns to the same shell with its history and environment intact. exit / Ctrl-D ends the session and the next opening starts fresh. A toolbar button syncs the active file pane to the shell's current working directory; when tmux is running, tmux display-message is queried so the active tmux pane's cwd is reflected rather than the cwd that tmux was launched from.
• New File, New Folder, inline Rename, Move to Trash, and Reveal in Finder
• "Open With" submenu listing applications that can open the file, with an "Other…" picker
• Auto-refresh: each file pane updates automatically when its directory changes externally
• Compress selected items to a zip archive
• Extract zip archives
• Copy, Cut, Paste, Finder pasteboard interoperability, and same-name conflict handling
• Finder aliases and directory symlinks are resolved for navigation
• Search, hidden-file toggle, and sorting
• Multi-selection with Command-click
• Range selection with Shift + arrow keys, Shift-click, and mouse drag
• Subfolder search with progress and cancellation
• File-type icons in the file list
• Configurable file-list columns: visibility and order
• User-editable config.toml for design settings and shortcut overrides
• Finder-compatible tags: tag column, standard color tags, and custom tag names from the file-row context menu
• Resizable file-list columns by dragging column headers. Left-pane column widths are restored; right-pane column widths are temporary.
• Restores window size, visible panes, pane widths, active pane, and open folders

Keyboard

• Up / Down: Move selection in the active file pane or folder tree
• Shift + Up / Down: Extend the file-pane selection range
• Left / Right: Scroll the file list horizontally
• Tab / Shift + Tab: Cycle keyboard focus across left file pane → right file pane → built-in terminal (when visible). The folder tree is reachable by mouse click but does not participate in Tab cycling.
• Enter: Open the selected file or enter the selected folder
• Command + O: Open the selected item
• Command + [ / Command + ]: Back / Forward
• Command + Up: Parent folder
• Backspace: Parent folder
• Command + F: Search
• Command + N: New folder
• Command + Shift + N: New file
• Command + Return: Rename inline
• Command + Backspace: Move to Trash
• Command + C / X / V: Copy / Cut / Paste. When the clipboard holds no files, Cmd+V creates a new file from the clipboard content (spreadsheet → .csv, image → .png, URL → .url, rich text → .rtf, plain text → .txt) and opens it in inline rename.
• Command + Option + V: Move-paste
• Command + Shift + V: Paste as plain text (creates a .txt file, dropping any formatting). Configurable via [shortcuts] pasteAsText = "..." in config.toml.
• Command + A: Select all
• Command + R: Reload
• Command + T: Open a terminal app here
• Command + P: Toggle preview pane
• Command + \: Toggle split view
• Command + Shift + X: Swap left and right panes (split view only)
• Command + Shift + .: Toggle hidden files
• Command + Shift + T: New tab
• Command + W: Close tab
• Command + Shift + [ / Command + Shift + ]: Previous / next tab
• Command + Option + T: Toggle built-in terminal pane
• Command + Option + Shift + T: Focus built-in terminal pane

Command Line Launch

Open the installed app at the current directory:

open -a tfx "$PWD"

Open a specific directory:

open -a tfx /path/to/folder

Show the installed app version:

/Applications/tfx.app/Contents/MacOS/tfx -v

Show command-line help:

/Applications/tfx.app/Contents/MacOS/tfx -h

Startup layout and pane visibility can be overridden for one launch:

tfx -1                 # --single
tfx -2                 # --split
tfx -r                 # --restore
tfx -p                 # --preview
tfx -P                 # --no-preview
tfx -t                 # --terminal
tfx -T                 # --no-terminal
tfx -2 -P -t ~/Downloads

Do not use -n or --args; pass the folder as the item for open instead. --args is treated as a launch argument and does not use macOS's normal folder-open path.

If open -a tfx cannot find the app, or launches a different build, pass the app path directly:

open -a /Applications/tfx.app "$PWD"

If you have a wrapper such as /usr/local/bin/tfx, relative paths are supported:

tfx .

Configuration

tfx creates and reads its user configuration from:

~/Library/Application Support/tfx/

The current configuration supports compact [font], [colors], [opacity], [shortcuts], [terminal], [openWith], [naming], and [[commands]] blocks in config.toml:

version = 1

[font]
ui = "system"
mono = "monospace"
size = 13
# Per-pane overrides (optional). Empty family or size = 0 inherits the global mono / size.
# fileList         = "JetBrains Mono"   # fileListSize   — file rows, status line, archive view
# folderTree       = "SF Pro Text"      # folderTreeSize — folder tree + pinned list
# preview          = "Hiragino Sans"    # previewSize    — preview pane (rendered + source)
# terminal         = "Cica"             # terminalSize   — built-in terminal pane

[colors]
fileListBackground = "#020A12"
fileForeground = "#D6F7FF"
directoryForeground = "#66D9FF"
headerForeground = "#8AEFFF"

[opacity]
background = 1
inactivePane = 0.5

[shortcuts]
reload = "cmd+shift+r"
togglePreview = "cmd+option+p"

[terminal]
app = "/Applications/Ghostty.app"

[openWith]
md = "com.microsoft.VSCode"
pdf = "/Applications/Preview.app"

[naming]
language = "auto"   # "auto" (follow system), "en", or "ja". Controls the placeholder names for New File, New Folder, and clipboard paste (e.g. `Untitled.txt` vs `名称未設定.txt`, `clipboard.csv` vs `クリップボード.csv`).

[[commands]]
name = "Git Pull"
run = "git -C {cwd} pull --ff-only"
target = "current"
requireGit = true
terminal = true
shortcut = "cmd+shift+g"

See docs/configuration.md for supported keys, design token mapping, examples, and error handling. Japanese documentation is available at docs/configuration.ja.md.

Build

xcodebuild -project tfx.xcodeproj -scheme tfx -destination 'platform=macOS' -derivedDataPath /tmp/tfx-derived CODE_SIGNING_ALLOWED=NO build

Release build:

xcodebuild -project tfx.xcodeproj -scheme tfx -configuration Release -destination 'platform=macOS' -derivedDataPath /tmp/tfx-release-derived CODE_SIGNING_ALLOWED=NO build

Project Structure

Source directories:

• tfx/App: App entry points and root view wiring
• tfx/TerminalFileManager: Top-level file manager screen, controls, keyboard routing, and layout state
• tfx/FileBrowser: File browser model, directory loading, selection, file operations, zip archive browsing, metadata, and drag/drop behavior
• tfx/FilePane: File list panes, rows, headers, menus, settings, and status line
• tfx/FolderTree: Folder tree and pinned-folder UI
• tfx/Preview: Preview pane, Markdown/PDF/video/Quick Look previews, preview metadata, and preview type selection
• tfx/Infrastructure: Small reusable AppKit and SwiftUI helpers
• tfx/Assets.xcassets/AppIcon.appiconset: App icon assets

Supporting directories:

• tools/generate_app_icon.swift: App icon regeneration script
• CHANGELOG.md: Release history

Documentation

See docs/README.md for the documentation index, maintenance rules, source layout guide, detailed design, implementation history, and roadmap.

License

tfx is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Third-party notices are listed in THIRD_PARTY_NOTICES.md.

Notes

• Delete-like operations use the macOS Trash instead of permanent deletion.
• Previews use PDFKit, AVKit, WebKit, and Quick Look.
• Date display uses yyyy-MM-dd HH:mm:ss.