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 non-blocking latest-wins folder scans, keyboard-aware entries, comfortable controls, compact-screen context menus, a proportion-locked theme-aware vector icon family with a gentle hover lift, and persistent grid zoom from 60% to 200% (Ctrl+scroll included).
• Refined Locations, Recent, and Pinned sidebar with bounded session recents, history destination menus, breadcrumbs, location entry, and current-folder search. Back, Forward, Parent, Home, location, search, sidebar, and direct List/Grid commands share standard shortcuts, visible hints, and searchable Quick Actions.
• A Devices sidebar section for mounted removable volumes (udisks mount locations) and network shares (NFS, SMB, SSHFS, and friends), refreshed every few seconds, with click-to-open and right-click Eject through gio. The section header's link icon opens Connect to Server, which mounts GVfs addresses such as smb://, sftp://, nfs://, and dav://; recent addresses are remembered as one-click chips in the dialog.
• Live status bar with item counts, selection summaries, and free disk space for the current filesystem, plus a window title that tracks the open folder.
• Rounded, drag-reorderable workspace tabs with independent location, search, and back/forward history; keyboard cycling; closed-tab reopening; folder context actions; drag-hover activation for direct cross-tab transfers; and private, byte-preserving folder/tab restoration across launches.
• A searchable Ctrl+K Quick Actions palette for common file, tab, view, navigation, terminal, Properties, Settings, and context-matched external plugin workflows.
• Optional two-pane browsing with independent folders, tabs, history, searches, selections, and bounded background scans; press F3 to toggle it and F6 to focus the other pane. Narrow windows keep both pane states alive while showing one at a time, and both pane workspaces are restored across launches.
• 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 by keyboard, range, or blank-canvas marquee; copy, cut, paste, duplicate, inline rename, trash, permanent delete, and undo on a responsive asynchronous operation lane with live progress.
• Nautilus-compatible desktop file clipboard support for copying and cutting files between Guth windows and other Linux file managers.
• Persistent Trash restore actions backed by .trashinfo metadata, including safe restore naming when the original path is occupied.
• 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 verified executable discovery, persistent enable controls, strict reviewed-version and capability checks for official plugins, and an opt-in schema-2 GUI action protocol. Enabled contributors are probed asynchronously with fixed time and data limits, matched against the current selection, surfaced in context menus and Quick Actions, and required to supply host-confirmed warnings for destructive actions.
• 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 folders, sidebar folders, or tabs to move them by default; hold Ctrl while releasing to copy instead. Drop on Trash to discard, drag out through native X11/XWayland file-copy semantics, or drag external files onto a folder, tab, or the current canvas to copy them into Guth. Native Wayland is available as an automatic fallback on systems without XWayland.
• 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 System (Auto), Cyan, Cupertino Light, Cupertino Dark, Nordic, Slate Pro, Rosé Pine Dawn, Rosé Pine Moon, Catppuccin Latte, Catppuccin Mocha, Purple, Matrix, Paper, Graphite, Studio, Sage, Neon, Cypherpunk, Ember, Ocean, and aev themes. System follows the desktop light/dark preference when exposed; Cupertino presets use soft macOS-inspired surfaces, Rose Pine brings warm editorial focus, and Catppuccin adds calm pastel contrast. A Comfortable/Compact/Spacious density switch tunes rows, tiles, controls, and keyboard navigation as one coherent layout system.
• Explicit limits for scans, searches, operations, thumbnails, previews, launchers, history, logs, and undo state.

Recent release

Guth 0.2.32 and guth-cli 0.1.3 are the current release line. This release turns navigation into one coherent system: Back, Forward, Parent, Home, location entry, folder search, sidebar control, and direct List/Grid modes now appear in Quick Actions with standard shortcuts, matching hover guidance, and clear status feedback. Linux startup now prefers X11/XWayland for complete desktop clipboard and drag-out behavior, then automatically falls back to a dynamically loaded native Wayland backend when no X display exists; View Options reports the active window system and explicit CLI/environment overrides are available.

The visual quality gate now checks every palette's primary, secondary, muted, accent, status, focus, and selection colors against both panel and workspace surfaces. The stronger gate drove targeted readability refinements in Cupertino Light, Nordic, Slate Pro, Rosé Pine Dawn, Catppuccin Latte, Paper, and Sage without flattening their individual character. Guth remains independent of GTK/GDK runtime versions and retains the four palettes from 0.2.31, density profiles from 0.2.30, the optional two-pane workspace, desktop and cross-pane drag-and-drop, safe archive workflows, XDG Open With, and bounded schema-2 plugin actions.

See CHANGELOG.md for the complete release notes. Generated session data is ignored and excluded from source packages.

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 its UUID, executable path, version, and every required capability, then 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.

Plugin refresh accepts only valid UUIDv7 manifests backed by safely owned executable files that are not group- or world-writable. Rejected manifests appear as bounded health diagnostics in Settings. Refresh is non-destructive: a temporarily unavailable plugin does not lose its saved enabled state. An outdated or incomplete Guth Sync manifest is shown as incompatible with an Update Guth Sync action instead of exposing partial sync controls.

External GUI Action Plugins

Schema-1 command manifests remain compatible. A plugin can explicitly opt into desktop actions with manifest schema 2, the gui-actions capability, and contributions.actions.protocol = 1. Guth never loads plugin code into its process: enabled contributors receive a bounded JSON context on standard input through the fixed --guth-action-protocol 1 probe|invoke command, and responses are identity-checked before anything is shown. Paths include authoritative hexadecimal Unix bytes so non-UTF-8 names survive the protocol.

Probe responses declare labels, descriptions, host-owned icons, context-menu and/or command-palette placement, selection bounds, accepted entry kinds/extensions, and whether an action is destructive. A destructive declaration without confirmation text is rejected. Probes time out after two seconds; one invocation runs at a time, remains cancellable in Guth's status bar, and is terminated after five minutes. See guth-cli/README.md for the wire contract and a complete manifest example.

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.

Linux Display Compatibility

Guth's interface is built with Rust, egui, and eframe; it does not link to GTK or GDK, so the installed GTK/GDK version does not constrain the UI. The GTK_THEME environment variable is only one optional signal used by the System (Auto) color palette. During --install-desktop, gtk-update-icon-cache and update-desktop-database are best-effort cache helpers; missing helpers do not prevent installation.

The default auto window mode chooses the most capable available desktop path:

1. If DISPLAY is available, Guth uses X11 or XWayland. This preserves the Nautilus-compatible desktop file clipboard and complete outbound XDND file dragging.
2. If no X display exists but WAYLAND_DISPLAY does, Guth starts natively on Wayland. Native inbound file drops work, while outbound file drag and the X11 desktop file clipboard are unavailable because the current window API does not expose the initiating Wayland pointer serial.

Use guth --window-backend x11 or guth --window-backend wayland to override automatic selection. The Wayland client library is loaded dynamically only when needed. Cargo installations compile against the host system, which is the safest path for older distributions; the default Glow renderer, GLES shader fallback, WGPU renderer, and software-preferred GPU modes remain selectable for different graphics stacks.

Keyboard Shortcuts

Drag And Drop

• Drag across blank space in the file canvas to marquee-select intersecting items; hold Ctrl, Cmd, or Shift to add those items to the existing selection. Workspace tabs can be dragged onto another tab position to reorder them.
• Within Guth, a selection dropped on a visible folder, sidebar folder, or tab moves by default. Hold Ctrl (Cmd where supported) at release to copy instead, or Ctrl+Shift to open an explicit Copy/Move chooser for the drop; the drag overlay announces the pending action. Drop on Trash to discard, drag out through native X11 file-copy semantics, or drag external files onto a folder, tab, or the current canvas to copy them into Guth. Holding a drag near the file canvas edge auto-scrolls long folders.
• Hovering another tab during a drag activates its folder. Folders can also be dropped on the Pinned or plugin-enabled Sync Folders targets to add shortcuts without moving their contents.
• Native X11/XWayland drag-out advertises a file copy, serves URI and selection metadata throughout the protocol handshake, and retries lost stationary-pointer acknowledgements without flooding the target. The source remains in Guth when another desktop application accepts it. Files dragged in from the desktop are copied to the pointed folder, tab, or current canvas; external folders dropped on Pinned or Sync Folders are added as shortcuts. Automatic backend selection prefers this complete X11/XWayland path. On a pure native Wayland session Guth still accepts inbound drops, and Settings reports why direct outbound drag is unavailable.

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. For other files, right-click Open With... opens a bounded application chooser discovered recursively from the desktop's XDG launcher entries. Guth honors localized names, desktop visibility, TryExec, hidden overrides, and MIME declarations, placing the most relevant handlers first. Checking Remember stores that application as Guth's default for the file's extension, so plain Enter opens it directly afterwards. Launcher %f/%F arguments preserve raw Unix file names, while %u/%U receive correctly percent-encoded file:// URIs. 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.
• Extract Here unpacks .tar, .tar.gz, .tgz, and .zip archives into a fresh collision-suffixed folder. A complete preflight rejects traversal, escaping links, duplicate or conflicting paths, special tar entries, oversized names, excessive entry counts, and excessive declared output before anything is written. Later I/O failures still leave an identity-tracked, undoable partial extraction.
• Compress to Archive and Compress to ZIP pack any selection into an atomically placed .tar.gz or .zip. Directories recurse in sorted order, duplicate output names are rejected, symlinks are preserved as links, special files are skipped with a warning, and the result is undoable like other created files. ZIP creation rejects names it cannot represent losslessly instead of silently changing raw Unix filenames.
• 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.
• Copy, move, duplicate, trash, and restore preserve raw Unix filenames, including names that are not valid UTF-8, while collision suffixes retain the original extension.
• Linux rename and same-filesystem move use atomic no-clobber semantics, preventing an entry created after validation from being overwritten.
• Operation source count, traversal item count, and traversal depth are bounded.
• File operations run away from the UI thread; new operation and drop requests are rejected while one is active, and window close is blocked until the active operation finishes.
• 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 --window-backend auto
guth --window-backend x11
guth --window-backend wayland
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_WINDOW_BACKEND=auto|x11|wayland
• 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 bounded private workspace.conf stores only pane/tab folder paths and active indices with 0600 permissions; selection, search text, clipboard data, and operation history are intentionally never persisted. Passing a folder on the command line overrides workspace restoration for that launch.

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. System (Auto) follows COLOR_SCHEME or GTK_THEME when the desktop exposes a preference and otherwise falls back to Guth Cyan Dark. Cupertino Light/Dark provide restrained macOS-inspired light and graphite surfaces, Nordic uses a cool blue-grey workspace, Slate Pro provides a crisp neutral light workspace, Rosé Pine adds warm Dawn/Moon surfaces, and Catppuccin adds pastel Latte/Mocha surfaces. Each palette carries a deliberate corner profile (soft, balanced, or crisp) so dialogs, rows, tabs, and drop targets keep a coherent visual rhythm. Density profiles are persisted as compact, comfortable, or spacious and adjust list/grid geometry and control spacing together. 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, CHANGELOG.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.