Guth

Guth is a native Rust file manager for fast, bounded local desktop workflows. It combines a compact professional interface with asynchronous previews, explicit resource limits, undoable operations, and Linux desktop folder integration.

Highlights

• Responsive, viewport-virtualized grid and list views with keyboard-aware entries, compact-screen context menus, and a proportion-locked theme-aware vector icon family.
• Refined Locations, Recent, and Pinned sidebar with bounded session recents, history destination menus, breadcrumbs, location entry, and current-folder search.
• Debounced, cancellable recursive search on one bounded background worker, with containing-folder context for every result.
• Image thumbnails and optional ffmpeg video posters and hover strips.
• Adaptive inline image, video, text, code, Markdown, CSV, and log previews with file metadata, navigation, zoom, and explicit loading or failure states.
• Multi-selection, range selection, copy, cut, paste, duplicate, rename, trash, permanent delete, and undo.
• Blank-space, file, and folder context menus with current-folder basics and folder-targeted paste and creation.
• Right-click Copy To and Move To workflows with typed paths, quick destinations, validation, collision-safe naming, and undo.
• UUIDv7 external command plugins shared with the guth-cli headless companion, including refreshable, persistent enable controls for the separate Guth Sync rsync plugin.
• Plugin-gated Sync Folders in the left sidebar, with independent persistent shortcuts, right-click add/remove actions, drag-to-pin folder targets, and authoritative per-profile or all-profile local read-only controls through Guth Sync.
• Plugin-gated Guth Caery context actions for audio-to-audio, video-to-video, and video-to-audio conversion through caery-lib.
• Drag selected entries onto visible or sidebar folders to move them, onto Trash to discard them, or out of Guth into desktop applications with native file-copy semantics. Drag external files onto a folder or the current canvas to copy them into Guth.
• Middle-click a folder to open it in a new Guth window without changing the current location.
• Viewport-responsive floating Properties, Settings, dialogs, and input-isolated quick-look previews instead of a permanent inspector pane.
• Original cyan Guth artwork plus persistent Cyan, Purple, Matrix, Paper, Graphite, Studio, Sage, Neon, Cypherpunk, Ember, Ocean, and aev themes.
• Explicit limits for scans, searches, operations, thumbnails, previews, launchers, history, logs, and undo state.

Install

Install the published binary with Cargo:

cargo install guth

Install the optional headless plugin host on desktop or server machines:

cargo install guth-cli
guth-cli plugins

Guth Sync and Guth Caery are optional plugins distributed through crates.io. Open Guth Settings and choose Install Guth Sync or Install Guth Caery. Guth installs the exact reviewed crate version with Cargo, verifies the executable and plugin manifest, and enables it. The computer needs cargo; Guth Sync additionally needs OpenSSH and rsync 3.2.5 or newer, while Guth Caery needs FFmpeg with the encoders documented by the plugin.

If either plugin is already installed manually, use Refresh plugins and enable its card. Sync controls then appear in Settings and the Sync Folders sidebar; conversion actions appear when one supported audio or video file is right-clicked.

Run Guth in your home folder or open a specific directory:

guth
guth /path/to/folder

Linux Folder Integration

Install Guth's embedded desktop entry for file-manager discovery and Open With support:

guth --install-desktop

Install the entry and make Guth the default handler for inode/directory:

guth --set-default

--set-default intentionally invokes xdg-mime. --install-desktop only invokes it when migrating an existing KnottFiles default association to Guth; normal startup never changes the default file manager.

The installed desktop entry uses the exact UTF-8 executable path returned by the running Guth binary, so it does not depend on the desktop session inheriting Cargo's PATH.

Keyboard Shortcuts

Knotwork Previews

Guth includes the Knotwork registry with two bundled preview plugins:

• Knotlook Media uses one active image worker plus the latest pending request, preserves source dimensions, shows transparency correctly, and uses the thumbnail pipeline for video posters and strips.
• Knotread Text uses one active reader plus the latest pending request, reads at most 2 MiB and 2,000 lines, detects likely binary files, labels truncation/lossy UTF-8, and provides a compact line-number and case-insensitive find toolbar.

Previewable files open inline by default when their plugin is enabled. Shift+Enter and Open Externally always route to the system application. The viewer supports toolbar and arrow-key zoom, mouse-wheel zoom over image/video stages, drag-to-pan above the fitted scale, and double-click reset to the fitted view. Media and text scaling are independent, and preview shortcuts act only on the displayed file rather than the file canvas behind it.

The primary file canvas lays out only viewport rows, uses rendered font measurements for middle elision, and adapts list metadata columns to the available width. Keyboard movement keeps the focused item visible, and sort changes reorder the loaded snapshot without rescanning the directory.

Filesystem Safety

• Ordinary delete moves items to the Freedesktop local trash.
• Permanent delete requires an explicit confirmation click and cannot be accepted with Enter.
• Destination paths inside a copied/moved source are rejected to prevent recursive self-copy.
• Conflicting destinations receive copy, copy 2, and similar names instead of overwriting data.
• Operation source count, traversal item count, and traversal depth are bounded.
• Undo is bounded and best-effort. A failed multi-item undo may have applied earlier items, so the consumed action is not re-queued with stale paths.
• Operation and thumbnail worker disconnects are recovered instead of wedging the UI.
• External child processes are reaped through a bounded watcher pool.

Renderer Options

Guth uses egui_glow by default and also compiles the WGPU renderer:

guth --renderer glow
guth --renderer glow --gles 2
guth --renderer wgpu --wgpu-backend vulkan,gl --wgpu-power high
guth --gpu preferred
guth --no-vsync

Environment equivalents:

• GUTH_RENDERER=glow|wgpu
• GUTH_GPU=required|preferred|off
• GUTH_GLES=1|2
• GUTH_WGPU_BACKEND=vulkan,gl,metal,dx12,primary,secondary
• GUTH_WGPU_POWER=high|low
• GUTH_FRAME_LATENCY=<positive integer>
• GUTH_VSYNC=true|false

Configuration

Preferences are stored at $XDG_CONFIG_HOME/guth/preferences.conf, or ~/.config/guth/preferences.conf when XDG_CONFIG_HOME is unset. Pinned folders and Sync Folder shortcuts are stored beside it in bookmarks.conf and sync-folders.conf.

The configuration is intentionally plain text and is replaced atomically when settings change. Guth Cyan Dark is the default and uses near-black surfaces with cyan action and focus accents. Background paths remain drafts until Apply, while opacity changes preview live and persist when adjustment ends. Unknown palette values fall back to the default theme. Legacy palette and opacity values migrate without discarding their relative intensity within the tighter readability ranges.

On launch, Guth copies missing knottfiles/preferences.conf and knottfiles/bookmarks.conf files into the Guth configuration directory without overwriting Guth files. Missing files are retried on later launches.

Build And Verify

cargo run -- /path/to/folder
cargo fmt --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo package --list

The crates.io payload is restricted in Cargo.toml to Rust sources, desktop data, README.md, LICENSE, and Cargo manifests. Local notes, generated targets, editor state, screenshots, and session artifacts are not packaged.

Project Layout

License

Guth is available under the MIT License. See LICENSE.