Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

34 Commits
AI
AI
 
 
docs
docs
 
 
scripts
scripts
 
 
src/biome_fm
src/biome_fm
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 
uv.lock
uv.lock
 
 

Repository files navigation

biome-fm — Dual-Pane File Manager with AI That Actually Operates Files

biome-fm screenshot

MIT License Stars Last Commit
Python 3.12+ Qt 6.7+ v0.32.0
PySide6 pluggy AI backends

Total Commander-style dual-pane file manager with a built-in AI that reads your filesystem and executes file operations on your behalf — locally, over SFTP, or inside archives.

biome-fm is a keyboard-driven dual-pane file manager built on PySide6. The left pane and the right pane stay in sync while an embedded AI chat watches both. You describe what you want in plain English — the AI calls the same VFS layer the UI uses and does it. No copy-paste of paths, no shell scripting, no context-switching. It runs on macOS, Windows, and Linux, and connects to Claude, OpenAI, and Ollama out of the box.

Why biome-fm?

  • Stop alt-tabbing. Terminal, diff viewer, hex editor, archive browser, image preview, PDF reader, git-diff — all tabs inside the same window.
  • AI that operates, not just advises. The chat panel has write access to the VFS. Ask it to reorganize a folder and it executes the moves with undo support.
  • Extensible by design. pluggy hooks let you add VFS backends, preview renderers, AI providers, and themes as isolated plugins without touching core.
  • Cross-platform, no compromise. One codebase, native look on macOS, Windows, and Linux. TOML theming with glass effects ships out of the box.

What you can say

"Move all PDFs older than 30 days into archive/2024/"

"Rename these 47 screenshots to kebab-case using their EXIF dates"

"Find duplicate images in this folder and show me a side-by-side comparison"

"What changed in this repo since last Tuesday? Show me the diff."

Quick Start

Prerequisites: Python 3.12+, uv

uv tool install biome-fm
biome-fm
Install from source 
git clone https://github.com/german-krasnikov/biome-fm.git
cd biome-fm
uv sync
uv run biome-fm
Compatibility
Component Minimum Tested
Python 3.12 3.12
PySide6 6.7 6.8
OS macOS, Windows, Linux macOS
Development setup 
uv sync --all-extras
uv run pre-commit install
uv run pytest

Optional extras: ai (Anthropic + embeddings), perf (Rust bindings for speed).

Features

File Operations

  • Async copy/move with progress bar + cancel
  • Conflict resolution dialog with per-file decisions
  • Transfer queue panel (pause, reorder, retry)
  • Create/extract archives (zip, tar, encrypted 7z + plugin extensions)
  • Checksum dialog (MD5, SHA-256)
  • Verify after copy (SHA-256 source vs destination; raises VerifyError on mismatch)
  • Undo/redo — 50 levels, every mutation is a Command
  • Dry-run preview before destructive operations
  • Batch execute on selection with template substitution
  • Space reclaimer — find and remove large/duplicate files
  • Clipboard history ring (last 20 entries)
  • ChownCmd with full undo support

UI & Navigation

  • Dual-pane, multi-tab layout with named workspaces; workspace switcher dialog
  • Breadcrumb bar with drag-and-drop path segments
  • Sidebar: Smart Folders, volumes + usage bar, bookmarks, recent projects, recent locations
  • Tab lock (ignores sync-browse navigation) and tab link (mirrors navigation between tabs)
  • Embedded terminal (Ctrl+), full-screen subshell toggle (Ctrl+O), clickable file:line` errors
  • Inline rename (F2), batch rename with metadata fields (EXIF, MP3 tags)
  • Flat/recursive view, TC-style file marks
  • OmniBar — unified navigation, command, and search in one input
  • Command palette (Ctrl+P) with frecency ranking, F1-F10 action bar
  • Gallery view with async thumbnail loading
  • Directory comparison panel (side-by-side diff)
  • Custom toolbar builder
  • Per-directory view state, path autocomplete
  • Global UI zoom (Ctrl+=/Ctrl+-), word wrap and text zoom in preview
  • Mouse back/forward buttons + trackpad two-finger swipe
  • macOS Touch Bar stub
  • Session view mode persistence across restarts

Search & Filter

  • Quick filter with character highlight
  • Select by pattern (glob/regex)
  • Fuzzy finder (Ctrl+P), virtual search pane
  • Reusable search templates
  • Advanced filter predicates: size:>10m mod:today ext:py
  • Spotlight/mdfind scope on macOS

Preview

  • Syntax-highlighted code and Markdown (Pygments)
  • Images, video thumbnails (ffmpeg), audio metadata (mutagen)
  • Archive contents, hex dump, git diff, PDF text
  • macOS Quick Look fallback, fullscreen viewer (F11)
  • "Ask AI" button sends preview content directly to the AI chat panel
  • Preview cache with 60 s TTL
  • Finder Comments + xattr browser in PropertiesDialog

VFS Backends

  • Local, SFTP/SSH (jump host, tunnel), S3 (with object versioning), WebDAV
  • ZIP/TAR/7z/RAR archive browsing
  • ISO 9660 and macOS DMG virtual filesystems
  • Docker container filesystem browser
  • FISH protocol VFS; extfs-style Script VFS (RPM, DEB, ISO)
  • rsync backend for delta-transfer; cross-VFS streaming resume
  • Plugin-defined custom VFS backends

Automation & Scripting

  • Python scripting engine (BiomeContext + ScriptingEngine) — automate any UI action
  • Keyboard macro recorder/player with persistent macro store
  • Watch rules — auto-actions triggered on folder events
  • IPC: Unix socket server + REST API (Bearer token, EventBus dispatch)

AI Integration

  • Multi-model chat: Claude, OpenAI, Ollama, CLI backends (Claude Code, Codex, OpenCode)
  • AI rename suggestions, context-aware file actions
  • Natural-language operations (Ctrl+Shift+N)
  • AI commit message suggestion from staged diff
  • Metadata-based renaming using EXIF/MP3 fields via AI
  • AI shell command detection

Themes & Appearance

  • TOML token-based themes with inheritance
  • Color-blind safe theme (Okabe-Ito palette)
  • Glass/opacity effect, file-type coloring, active-pane highlight
  • Custom column visibility

Plugins

  • 8 pluggy hookspecs: context menu, custom columns, archive formats, themes, and more
  • entry_points discovery + local drop-in plugins
  • Versioned plugin API
  • Plugin-defined custom columns and presigned URL generation
Plugin example 
# ~/.config/biome-fm/plugins/my_plugin.py
class Plugin:
    BIOME_FM_API_VERSION = (1, 0)

    def context_menu_actions(self, items, pane_id):
        return [ActionSpec(label="Open in Obsidian", callback=lambda: ...)]

Or register via pyproject.toml:

[project.entry-points."biome_fm.plugins"]
my_plugin = "my_plugin:Plugin"

Architecture

Source tree 
src/biome_fm/
├── models/        # VFS router, FileItem, DirectoryModel
├── presenters/    # Qt-free MVP logic
├── views/         # Passive PySide6 widgets (signals only)
├── commands/      # Command pattern — execute() + undo()
├── operations/    # Async queue (ThreadPool + cancel tokens)
├── preview/       # Provider protocol + renderer registry
├── plugins/       # pluggy hookspecs + entry_point discovery
├── ai/            # AIProvider protocol + concrete providers
├── ipc/           # Unix socket server + REST API (Bearer token)
├── scripting/     # BiomeContext + ScriptingEngine (Python automation)
├── cli/           # CLI installer (configure/doctor)
└── themes/        # TOML color token resolution

Hybrid Supervising Controller (MVP variant). Views are passive — they emit signals and render what they're given, holding zero business logic. Presenters subscribe to those signals, run all decisions, and push state back through a typed Protocol interface. Every file mutation is a Command subclass with execute() and undo(), stored in a 50-level CommandHistory. The VFS layer (VFSRouter) dispatches transparently across local paths and archives so presenters never branch on location type.

Full architecture: AI/architecture.md

Recent Changes

v0.33.0 — 2026-07-25 — Plastic SCM plugin (full feature set)
  • PlasticPlugin — Ctrl+Shift+P opens PlasticWindow; on_navigate detects .plastic/ workspace; context-menu Diff/Undo/Checkin actions
  • 12-page sidebar: Pending Changes, Changesets, Branches, Labels, Shelves, Reviews, Xlinks, Admin, Branch DAG, Workspaces & Repos, Triggers, Git Sync
  • All cm ops run off main thread via ThreadPoolExecutor + SimpleQueue drain
  • Commit graph column with GraphDelegate; inline diff panel; branch tree with prefix grouping; CS master-detail with CSDetailWidget
  • cs_log_files() for cloud/Unity Plastic compatibility; three-way merge viewer; side-by-side diff
  • ~750 unit tests + ~100 integration tests in tests/unit/plastic/ and tests/integration/
v0.32.0 — 2026-07-24 — Security, performance, and 34 architectural fixes
  • Shell injection hardened; Zip Slip protection; API keys moved to CredentialStore
  • Chunked async dir loading; AI calls off main thread; bounded thread pool
  • VFS Protocol split into ReadableVFS + WritableVFS; atomic_write_json for all stores
  • Dead code purge (~2900 LOC); run_git() centralized; session auto-save
v0.31.0 — 2026-07-21 — Session, clipboard history, macros, REST API
  • Session Save/Restore: view_mode field persists gallery/list mode per pane
  • Clipboard History Ring (20-entry deque); Keyboard Macro Recorder (MacroStore)
  • REST API for Remote Control (ipc/rest_server.py, Bearer token auth)
  • Directory Comparison View; Custom Toolbar Builder
v0.30.0 — 2026-07-21 — Gallery view, Omnibar, dry-run preview, fullscreen shell
  • Thumbnail Gallery View — async 128×128 thumbnails, 500-entry LRU cache
  • Unified Omnibar — Spotlight-style overlay for path nav, commands, and search
  • Operation Dry-Run Preview — cmd.preview() shown before execute
  • Full-screen Subshell Toggle (Ctrl+O)
v0.29.0 — 2026-07-21 — Remote VFS: FISH, Script, ISO, DMG, Docker, rsync
  • SSH jump host / proxy command support; cross-VFS streaming resume
  • FISH VFS; extfs Script VFS; ISO 9660; macOS DMG; Docker container FS; rsync
  • Plugin-defined custom columns (column_value hookspec)

Full history: CHANGELOG.md

Documentation

Resource Description
AI/architecture.md Technical architecture, VFS router, MVP pattern, threading model
docs/ User-facing guides: keyboard shortcuts, plugin authoring, AI setup
.claude/skills/ Development patterns for contributors (PySide6, TDD, VFS)
CHANGELOG.md Full release history

FAQ

Is this Total Commander for Mac?

Inspired by Total Commander and Midnight Commander — dual-pane, keyboard-driven, archive browsing. The difference: native cross-platform look via PySide6 and an optional AI layer for rename suggestions, natural-language ops, and file summaries.

Does it work without AI / an API key?

Yes. The default provider is NoOpProvider — all AI features are hidden when no provider is configured. Everything else works fully offline.

Can I write plugins?

Yes. biome-fm uses pluggy hooks. Drop a .py file in ~/.config/biome-fm/plugins/ or register via entry_points in your package. See docs/ for a walkthrough.

How does it handle 100k+ files?

Directory scanning uses scandir-rs (Rust) with a Python fallback. The file list uses QAbstractItemModel with lazy loading and uniform row heights — Qt never measures rows it hasn't painted.

Contributing

Bug reports and PRs welcome. Please open an issue before large changes. See CLAUDE.md for the dev workflow and agent conventions.

License

MIT — Built by German Krasnikov

About

AI-powered cross-platform dual-pane file manager. Python + PySide6/Qt.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages