lgse/strata

Strata

Navigate every layer. A fast, keyboard-first file manager for modern Linux desktops.

_{The animation respects reduced-motion preferences. View the static preview.}

Strata combines spatial Miller-column navigation with familiar Icons and List views, instant fuzzy filename search, rich previews, and native Linux desktop integration. It is designed for Omarchy and works on compatible GTK4 Linux environments.

• Features
• Installation
  • Interactive installation
  • AI-assisted installation
  • Manual installation
• Usage and desktop integration
  • Desktop entry
  • Make Strata the Omarchy file manager
  • Unlock encrypted volumes on Omarchy
  • Network shares
• Custom actions and script authoring
• Theming
  • Follow Omarchy Quattro
  • Bundled themes
  • Custom themes
• Release channels
• Under the hood
• Technical specifications
• Development and documentation
• Contributors
• License

• Three browser modes: navigable Columns, an Icons grid, and a sortable List table.
• Keyboard-first control: directional-key movement, navigation history, location entry, pane filtering, fuzzy search, file operations, and quick previews. An optional footer and F1 shortcut reference help you learn each mode; the footer also shows clipboard status. See keyboard navigation and paste destinations. Optional 10xer mode hides window and pane chrome and uses Yazi-style keys.
• Fast recursive search: press Ctrl+K to find files and directories by name or path while the tree is still being indexed. Global search covers Home and all mounted local drives, regardless of the current folder. Hover the search field to see the included locations. The dialog warns when results are incomplete; folder-scoped filtering/search remains separate. URI-native remote shares are not yet included.
• Rich previews and thumbnails: native rendered Markdown and static HTML, plus bounded previews for text, source code, images, camera RAW, PDF, audio, and video, with native parser-backed formats isolated from the application. Audio opens in a now-playing view with artwork and a live spectrum; video gets technical badges, a keyframe storyboard while scrubbing, ambient light around the frame, silent autoplay that eases its sound in, and Enter hands the position to your default player. File Properties shows available media resolution, duration, bitrate, codecs, HDR, subtitle and chapter counts, and audio/video rates. RAW previews and Properties also show dimensions, camera, lens, focal length, shutter speed, ISO, and GPS coordinates, with N/A for unavailable values.
• Shared storage properties: volumes and mounted storage entries in Devices use the same Properties dialog for name, device, filesystem, mount status, and available capacity/usage. Set label… saves a display label only in Strata; it never changes the filesystem label, mounts/unmounts a drive, or alters system configuration. Labels update the sidebar and Properties live and can be cleared to restore the normal device name. Formatting remains restricted to eligible removable drives; release actions follow the device's reported capabilities.
• Responsive filesystem work: cancellable directory loading, bounded streaming, incremental monitoring, stable selection, and virtualized large directories.
• Everyday file operations: create folders, rename, cut, copy, paste, trash, permanent delete, sorting, hidden files, pins, and history.
• Remote locations: browse GIO/GVfs locations such as authenticated SMB shares and SFTP servers from the location field, with explicit host-key decisions.
• Adaptive appearance: compact or airy density, six bundled themes, custom themes, and live Omarchy Quattro theme following.
• Updates in the app: automatic update checks (on by default; turn them off in Settings → Updates), release notes, verified downloads, and in-place installation for release binaries.
• Custom actions: add your own scripts to the file and folder context menus, with a manager in Settings → Actions and background progress in the Jobs dashboard. See Custom actions.
• System file chooser: opt in through Settings → General → System file chooser, the installer, or strata --install-portal; see portal setup.
• Encrypted-volume unlock: opt in through the installer, Settings → General → Desktop integration on Omarchy, or strata --install-udiskie-unlock; restore with strata --uninstall-udiskie-unlock (Settings Restore default on Omarchy only).

Arch Linux and Omarchy are the primary supported environments. Current binaries require glibc 2.39 or newer and the runtime libraries listed below.

The interactive installer detects the Linux architecture, glibc version, Arch Linux, and Omarchy 3 or 4. It installs the latest verified stable release and offers optional desktop-menu, default-folder-handler, "Open file location", system file chooser, encrypted-volume unlock, SMB, broader image/RAW, and Omarchy keybind integration:

curl -fsSL https://raw.githubusercontent.com/lgse/strata/main/install.sh | bash

The installer shows every privileged package operation before asking to run it. It verifies both the published SHA-256 digest and GitHub Actions provenance before installing anything from the release archive. The binary is installed per-user at ~/.local/bin/strata.

For an unattended Arch or Omarchy installation, pass --non-interactive. This installs required dependencies and the binary without prompting; optional integrations remain disabled unless explicitly selected:

curl -fsSL https://raw.githubusercontent.com/lgse/strata/main/install.sh \
  | bash -s -- --non-interactive \
      --with-smb \
      --with-raw \
      --with-desktop-entry \
      --with-folder-association \
      --with-omarchy-keybinds \
      --with-udiskie-unlock

Each --with-* flag implies --non-interactive, and folder association implies the desktop entry and --with-file-manager. Use --with-file-manager by itself to enable only "Open file location" integration. File chooser replacement is separate: use --with-file-chooser to opt in, or --without-file-chooser to keep your current chooser and dismiss the one-time in-app offer. Neither folder association nor an unattended install enables the chooser automatically. Encrypted-volume unlock is offered on Omarchy 3 or 4 (the installer asks; default No), and on generic Arch only when udiskie is already on PATH. The installer never installs the udiskie package. Unattended installs need --with-udiskie-unlock; --non-interactive alone and other --with-* flags leave it declined. Restore on Arch with strata --uninstall-udiskie-unlock, not Settings.

Non-interactive package installation requires passwordless sudo or cached credentials. Run ./install.sh --help for the full option list.

Phone backends are not installed by the script. For optional iPhone/iPad or Android access, follow Connecting phones after installation.

Use this option to have a coding agent install and verify the latest release archive.

Give this prompt to a coding agent with terminal access:

Install the latest stable Strata release from https://github.com/lgse/strata safely.

Before changing anything:
1. Confirm this is a glibc-based Linux system with a graphical GTK4 environment.
2. Detect whether the machine is x86_64 or aarch64 and select only the matching
   *-unknown-linux-gnu archive from the canonical lgse/strata GitHub release.
3. Show me the runtime packages you need and ask before using sudo or changing
   my default file-manager association.

Then:
- Install the required GTK4, GtkSourceView 5, Poppler GLib, Fontconfig, Bubblewrap,
  FFmpeg/GStreamer, and desktop-integration runtime dependencies using the system
  package manager. Add gvfs-smb only if I want SMB support.
- Ask whether I want phone access. On Arch/Omarchy, add gvfs-afc and usbmuxd for
  iPhone/iPad app documents, gvfs-gphoto2 for camera/PTP photo access, or gvfs-mtp
  for Android file transfers, only if requested. Other distributions need their
  equivalent GVfs backends.
- Download the archive and its matching .sha256 file from the latest GitHub release.
- Verify the checksum with sha256sum --check. If GitHub CLI is installed and
  authenticated, also verify GitHub Actions provenance with
  `gh attestation verify <archive> --repo lgse/strata`. Stop if either attempted
  verification fails; never install a binary with an invalid checksum.
- Extract it and install `strata` to ~/.local/bin/strata without overwriting an
  unrelated file. Ensure ~/.local/bin is on PATH.
- Ask whether I want a per-user desktop entry and inode/directory association;
  if yes, install the archive's io.github.lgse.Strata.desktop and io.github.lgse.Strata.svg
  under ~/.local/share, pointing Exec at the installed binary, then refresh the
  desktop database and icon cache.
- Separately ask whether Strata should handle "Open file location" requests. If
  yes, verify no other per-user service provides org.freedesktop.FileManager1,
  then install the archive's io.github.lgse.Strata.FileManager1.service under
  ~/.local/share/dbus-1/services with Exec pointing at the installed binary.
- Ask before editing udiskie config to use Strata for encrypted-volume unlock.
  Do not install the udiskie package. Do not send Arch users to Settings for
  this row; restore on Arch with `strata --uninstall-udiskie-unlock`.
- Launch `strata`, report its installed version/source release, and verify the
  desktop association if one was requested. Do not weaken the preview sandbox.

Install the release archive directly if you prefer to perform each step yourself.

case "$(uname -m)" in
  x86_64)  target=x86_64-unknown-linux-gnu ;;
  aarch64) target=aarch64-unknown-linux-gnu ;;
  *) echo "Strata has no prebuilt release for $(uname -m)" >&2; exit 1 ;;
esac
printf 'Use the %s release archive.\n' "$target"
getconf GNU_LIBC_VERSION   # must report glibc 2.39 or newer

On Arch Linux or Omarchy:

sudo pacman -S --needed bubblewrap ffmpeg ffmpegthumbnailer fontconfig \
  gstreamer gst-libav gst-plugins-base gst-plugins-good gtk4 gtksourceview5 gvfs poppler-glib
# Optional SMB, AppImage icon, and broader camera RAW support:
sudo pacman -S --needed gvfs-smb imagemagick libraw dcraw squashfs-tools

GTK 4.12 or newer and glibc 2.39 or newer are required. Other glibc-based distributions may work when they provide equivalent runtime libraries, but their package names and binary compatibility vary. Systems with an older glibc must build Strata from source.

Device discovery requires the GVfs UDisks2 volume monitor (gvfs on Arch and Fedora; gvfs-daemons on Debian/Ubuntu). Without that backend, removable drives may be absent from Devices. SMB support remains optional. Phones need additional backends; see Connecting phones.

From the latest release, download the .tar.gz matching $target and its identically named .sha256 file over HTTPS. Then verify its digest:

cd ~/Downloads
archive="strata-<version>-${target}.tar.gz"
sha256sum --check "${archive}.sha256"

If GitHub CLI is installed and authenticated, you can additionally verify the archive's signed GitHub Actions provenance before extracting it:

gh attestation verify "$archive" --repo lgse/strata

Every verification you run must succeed. Extract the archive, install the binary, and confirm it starts:

tar -xzf "$archive"
install -Dm755 "${archive%.tar.gz}/strata" "$HOME/.local/bin/strata"
command -v strata
strata

If command -v fails, add $HOME/.local/bin to your shell's PATH. Every archive contains SOURCE_COMMIT, identifying the exact source revision used by GitHub Actions.

Download the matching strata-<version>-<target>.debug asset from the same release and place it beside the installed strata binary, keeping its filename unchanged. Then run coredumpctl debug strata; GDB will load its Rust function names and source lines.

In-app updates verify signed release manifests inside Strata, without gh, a GitHub account, or a token. Releases published before signed manifests were introduced require manual installation; the updater never falls back to checksum-only verification.

For a manual installation, use Settings → Updates for verified in-app updates, or repeat the download, verification, and install steps for a newer release. An in-app update also refreshes an already installed desktop entry and application icon from the new archive; it never creates desktop metadata that was not installed before. If the user opted into Strata's system file chooser, the update restarts the portal frontend so subsequent dialogs use the newly installed build. Package-managed installations are updated only by their system package manager. To remove a per-user installation, run strata --uninstall-udiskie-unlock before deleting the binary if you opted into encrypted-volume unlock, then:

rm -f ~/.local/bin/strata \
  ~/.local/share/applications/io.github.lgse.Strata.desktop \
  ~/.local/share/dbus-1/services/io.github.lgse.Strata.FileManager1.service \
  ~/.local/share/icons/hicolor/scalable/apps/io.github.lgse.Strata.svg
update-desktop-database ~/.local/share/applications 2>/dev/null || true
gtk-update-icon-cache -qtf ~/.local/share/icons/hicolor 2>/dev/null || true

User preferences and custom themes remain under the XDG configuration directories so an uninstall does not destroy personal settings.

Launch Strata with an optional local directory:

strata                      # home directory
strata ~/Documents          # a specific directory
strata --unlock-volume DEVICE  # unlock an encrypted volume
strata --install-udiskie-unlock   # install Strata as the udiskie unlock handler
strata --uninstall-udiskie-unlock # restore the previous udiskie configuration
strata --version            # print the installed version

In the default map, useful shortcuts include Ctrl+K for recursive search, Ctrl+L for a path or URI, Ctrl+F to filter the current pane, Ctrl+Z to undo or Ctrl+Shift+Z to redo the latest reversible file operation, Space for preview, F2 to rename, and Alt+arrow keys for history and parent navigation.

Toggle 10xer mode with Ctrl+Shift+M for Yazi-style navigation and footer prompts; q returns to the default map. In 10xer mode, l/→ enters preview, h returns to the listing without closing it, and i toggles it.

In narrow or highly scaled windows, the file view takes priority: the preview shrinks, then hides when there is not enough room for both. Widening the window restores the preview and its session width automatically. Hidden previews pause playback and defer loading new selections; unchanged previews return without reloading the file.

Every release archive ships io.github.lgse.Strata.desktop and the Strata application icon io.github.lgse.Strata.svg. Install both to give Strata a per-user launcher with its own icon in launchers, docks, task switchers, and window overviews, and optionally make Strata the default directory handler:

cd ~/Downloads/"${archive%.tar.gz}"
install -Dm644 io.github.lgse.Strata.svg \
  ~/.local/share/icons/hicolor/scalable/apps/io.github.lgse.Strata.svg
install -d ~/.local/share/applications
sed "s|^Exec=strata |Exec=$HOME/.local/bin/strata |" io.github.lgse.Strata.desktop \
  > ~/.local/share/applications/io.github.lgse.Strata.desktop
update-desktop-database ~/.local/share/applications
gtk-update-icon-cache -qtf ~/.local/share/icons/hicolor 2>/dev/null || true
xdg-mime default io.github.lgse.Strata.desktop inode/directory
xdg-mime query default inode/directory

The final command should print io.github.lgse.Strata.desktop. The desktop entry's filename matches the io.github.lgse.Strata application ID that Strata's windows report, so desktop shells match a running window to this entry and draw its Icon value. Log out and back in if a shell caches launcher icons.

When building from source, mise run install-local installs the binary, icon, and desktop entry in the same locations, and mise run uninstall-local removes them.

Browsers and GTK/GNOME applications reveal a file by calling the org.freedesktop.FileManager1 D-Bus interface instead of consulting the inode/directory association. The interactive installer offers this separately; for unattended installation, pass --with-file-manager. Folder association enables it automatically.

For a source installation, enable Strata as the per-user activatable provider explicitly:

mise run install-file-manager

For an AUR package, copy its inactive service template into your per-user service directory:

install -Dm644 /usr/share/strata/io.github.lgse.Strata.FileManager1.service \
  ~/.local/share/dbus-1/services/io.github.lgse.Strata.FileManager1.service

For a release archive installation, install the included service manually instead:

cd ~/Downloads/"${archive%.tar.gz}"
install -d ~/.local/share/dbus-1/services
sed "s|^Exec=/usr/bin/strata |Exec=$HOME/.local/bin/strata |" \
  io.github.lgse.Strata.FileManager1.service \
  > ~/.local/share/dbus-1/services/io.github.lgse.Strata.FileManager1.service

A per-user provider takes precedence over system providers shipped by other file managers. Before enabling Strata manually, remove any other per-user service whose Name is org.freedesktop.FileManager1; two providers for the same name in one service directory are chosen arbitrarily. If another file manager already owns the bus name, exit it before testing. Use mise run uninstall-file-manager for a source installation, or remove the per-user service file, to disable Strata again.

Strata then answers ShowFolders, ShowItems, and ShowItemProperties, opening the directory that holds the named items with those items selected:

busctl --user call org.freedesktop.FileManager1 /org/freedesktop/FileManager1 \
  org.freedesktop.FileManager1 ShowItems ass 1 "file://$HOME/Downloads" ""

The XDG association above handles folders opened by applications. On current Lua-based Omarchy releases, also override the stock Nautilus shortcuts in ~/.config/hypr/bindings.lua so Omarchy launches Strata directly.

First inspect the active bindings and back up your user configuration:

omarchy menu keybindings --print | grep -i "file manager"
cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)

Append these overrides to ~/.config/hypr/bindings.lua:

-- Use Strata instead of Nautilus for Omarchy's file-manager shortcuts.
hl.unbind("SUPER + SHIFT + F")
hl.unbind("SUPER + ALT + SHIFT + F")
o.bind("SUPER + SHIFT + F", "File manager", { launch = "strata" })
o.bind("SUPER + ALT + SHIFT + F", "File manager (cwd)",
  "uwsm-app -- strata \"$(omarchy-cmd-terminal-cwd)\"")

The stock shortcut is Super+Shift+F, not Ctrl+Shift+F. To support the Ctrl chord too, first confirm that it is not assigned to another action, then optionally append:

o.bind("CTRL + SHIFT + F", "File manager", { launch = "strata" })

Apply and validate the configuration:

hyprctl reload
hyprctl configerrors
omarchy menu keybindings --print | grep -i "file manager"

hyprctl configerrors should produce no errors. These user overrides survive Omarchy updates; do not edit files under /usr/share/omarchy/.

On Omarchy 3 or 4, the installer asks whether to use Strata for encrypted-volume unlock (default No). Settings → General → Desktop integration includes Unlock encrypted volumes. Choose Use Strata so plugging in an encrypted drive opens Strata's password prompt instead of udiskie's dialog. Restore default returns udiskie to its previous configuration.

On generic Arch, the installer offers the same step only when udiskie is already on PATH. Restore there with strata --uninstall-udiskie-unlock; Settings for this row stays Omarchy-only.

The same setup is available unattended:

strata --install-udiskie-unlock
strata --uninstall-udiskie-unlock

This edits ~/.config/udiskie/config.yml and records restore state in ~/.local/share/strata/udiskie-install/state.toml. It is not a saved Strata preference. The Settings row appears only when Omarchy is detected and udiskie is on your PATH; the CLI flags are unattended and are not Omarchy-gated. Unattended installer opt-in is --with-udiskie-unlock.

Strata discovers and mounts phones through GIO/GVfs. The required phone backends are optional and are not installed by install.sh. On Arch Linux or Omarchy, install only the support you need:

# iPhone or iPad app documents (AFC):
sudo pacman -S --needed gvfs-afc usbmuxd
# Camera/PTP photo access, including compatible iPhones:
sudo pacman -S --needed gvfs-gphoto2
# Android (MTP):
sudo pacman -S --needed gvfs-mtp

Other distributions need equivalent GVfs AFC, gphoto2/PTP, or MTP backends; package names vary.

• iPhone/iPad: unlock the device, connect it with a USB data cable, and accept Trust This Computer (enter the device passcode if requested). AFC can expose an app document-sharing view containing folders named after apps; this is not the photo library. For photos, install the gphoto2 backend and look for a separate camera/device entry with DCIM, if exposed by the phone. Accept any photo-access prompt. Photos stored only in iCloud may not be available over USB. Access depends on the iOS version and backend support; iOS does not expose unrestricted internal storage.
• Android: unlock the device, connect it with a USB data cable, and select File transfer / Android Auto or MTP in its USB preferences rather than charging-only mode. Accept any file-access prompt. Only storage exposed by the phone is available, not protected system files or private app data.

After installing a backend, fully quit Strata (all windows) and reopen it. Reconnect the unlocked phone if necessary, then click its entry under Devices. The camera/PTP entry opens a single Photos view: files appear progressively from storage/date folders, prioritizing newer date-folder names, without requiring you to open each folder. The backend may finish a folder's metadata before returning its first batch. This is a virtual listing of JPEG, HEIC/HEIF, MOV, MP4, and recognized camera RAW files, not a reorganization of the phone. Sidecars such as .AAE and other formats are hidden only from this Photos view; their originals remain untouched and visible in normal folder browsing. Duplicate filenames remain separate files with their original locations; use Copy path or Properties to distinguish their sources. Preview, copy, and delete act on those originals. This is the USB-exposed collection, not iOS's Albums hierarchy. The current backend does not provide album membership for a reliable Albums/Camera Roll split.

Camera batches yield to interface input and redraws. In List view, file-type grouping is applied after discovery finishes; the saved grouping setting is preserved while the live listing stays ungrouped.

Discovery reads metadata, not every photo's contents. It skips symlinks, avoids revisiting discovered directories, and preserves hidden-file filtering. Photos keeps loading in batches until the whole exposed library is indexed, you navigate away or refresh, or the device reports an error. There is no overall scan deadline or fixed file, folder, or nesting limit. Refresh to rescan after a phone-side change; not every device supports live change notifications.

Android MTP and iPhone app-document/AFC entries retain normal folder browsing. For Android, open Internal storage (the label varies by device).

Still photos (including HEIC) and MOV/MP4 videos can use the preview pane or Space quick preview directly from the phone, without a manual copy. Strata first downloads a private temporary input for sandboxed decoding: up to 64 MiB in 30 seconds for images or 256 MiB in 60 seconds for videos, with at most four staged inputs per process. Video playback waits for that download, then reuses it for seeking and resizing. Closing or changing the preview cancels the request; temporary files are removed after the player and its workers release them. Remote PDFs, animated GIFs, audio, and other video formats still need a local copy for preview. HEIC decoding requires an installed HEIC-capable image decoder, such as ImageMagick with libheif. Camera/PTP thumbnails use small previews provided by the camera, with bounded retrieval and sandboxed decoding; if the camera cannot supply a thumbnail, Strata keeps the file icon instead of downloading the original. Camera thumbnails are cached only in memory. See Remote previews for cleanup, caching, and sandbox details.

If the phone is missing, check the backend package, try another data cable or USB port, and confirm the trust/file-transfer setting. On Arch/Omarchy, lsusb (from usbutils) can confirm USB detection, but detection alone does not establish file access. For iPhone/iPad, also check systemctl status usbmuxd.service while the phone is connected. If the newly installed backend still is not discovered after restarting Strata, log out and back in to refresh the desktop's GVfs services.

Some recent iPhones can expose an empty camera/PTP store with libgphoto2 2.5.34, even when unlocked, trusted, and holding locally stored photos. This is a known upstream libgphoto2 issue, not necessarily an empty photo library or a Strata display problem. The backend mishandles the folder-parent information returned by these devices.

A read-only test with an iPhone reporting iOS 26.6.1 reproduced the problem: unmodified libgphoto2 2.5.34 listed 0 folders, while the same version with upstream fix 9f5d4f9 listed 117 folders. Both builds were temporary, with their actual library loading verified; no photos were downloaded or modified. This confirms folder listing with the fix on that device, not complete transfer or Strata GUI coverage.

Use a distribution libgphoto2 update or backport containing that fix when available. Merely reinstalling gvfs-gphoto2 or restarting Strata will not fix an affected libgphoto2 build. Strata's GVfs camera backend must load the corrected library; setting library paths only for Strata may not affect the separately launched GVfs process. This documentation change does not bundle or install the fix. Avoid replacing system libraries manually; any locally built workaround should be isolated and reversible.

Press Ctrl+L, enter an address such as smb://server/share or sftp://user@host:2222/path, and press Enter. Strata uses GIO/GVfs and prompts for credentials when required. Remote protocols need their GVfs backend installed; distributions split these up differently, so check yours for the SMB backend (gvfs-smb on Arch) and the SFTP backend (part of gvfs on Arch, gvfs-backends on Debian and Ubuntu).

SFTP accepts password and SSH-key authentication. Encrypted keys can be unlocked in your SSH agent; if GVfs asks Strata for a key passphrase or host-key decision, Strata presents the request without deciding for you. See docs/remote-sftp.md, which also documents scripts/sftp-fixture.sh, a disposable OpenSSH server for testing.

Use Settings → Actions → New action… to create an action, or ask a coding agent to create the files below. Script → Library supplies editable Python and Bash recipes, sets their runtime, file filters, and Whole selection / Per item mode, and never saves or executes them merely by selecting them.

For Python and Bash, the Script tab reports whether the interpreter can be found. Python uses the script's shebang, or python3 when there is none. Availability is checked automatically when the dialog opens; reopen it after installing a runtime. Bash and Command do not need Python. This checks executable availability, not script syntax, safety, or dependencies such as ImageMagick, FFmpeg, or ExifTool.

Actions are ordinary, user-owned folders under ${XDG_CONFIG_HOME:-$HOME/.config}/strata/actions/:

strata/actions/log-selection/
├── action.toml
└── main.py

The folder name and manifest id must match. Use a new lowercase kebab-case id; do not overwrite an existing action. Create directories with mode 0700 and manifest/script files with mode 0600. Entry points are regular files with plain filenames, not symlinks or paths. Scripts need no executable bit: Strata invokes the interpreter. Command actions have only a manifest. Import/export transfers the manifest and declared entrypoint, not arbitrary helper files.

Example action.toml:

schema_version = 1
id = "log-selection"
name = "Log selected paths"
description = "Print the selection without modifying files"
icon = "terminal"
enabled = false
menu = "submenu"

[when]
kinds = ["file"]
min_items = 1

[run]
runtime = "python"
entrypoint = "main.py"
mode = "whole-selection"
on_error = "continue"
working_directory = "parent"
confirm = true

Keep generated actions disabled until the user reviews them. After hand-writing files, restart Strata to reload them, then review/enable the action in Settings. All selected entries must match the filters. Scripts are trusted local programs with the user's permissions—not sandboxed.

Put this in main.py; the helper is supplied by Strata at invocation time, with no pip installation or copied helper module:

#!/usr/bin/env python3
from pathlib import Path
from strata_actions import context

ctx = context()
for index, path in enumerate(ctx.paths, start=1):
    ctx.log(f"{index}: {Path(path).name}")
    ctx.progress(index, ctx.count, "Logging selected files")

• ctx.paths: absolute paths for this invocation; ctx.paths_bytes() preserves native filename bytes. ctx.count is their count, not the total per-item job size; ctx.single is the sole path or None.
• ctx.position / ctx.total: 1-based job position and job size in Per item mode, otherwise None. Whole-selection scripts enumerate ctx.paths themselves.
• ctx.parent: invoking folder. ctx.directory: stored action folder. ctx.run_directory: private temporary scratch, removed after the invocation.
• ctx.log(), ctx.progress(processed, total=None, message=None), and ctx.output(absolute_path) report to Jobs. output() only reports a location; the script must create it. Import require_tool(name) from strata_actions to explain missing dependencies.

See the complete maintained context() reference for identity, metadata, mode/source, and tool lookup. The Batch rename and Lowercase file names recipes additionally pass a per-file naming context to new_name(context); its filename and 1-based index are recipe-specific, and context.batch exposes the general Strata context.

For a Bash script, replace the manifest's [run] section with runtime = "bash", entrypoint = "run.sh", and mode = "whole-selection". Example run.sh:

#!/usr/bin/env bash
set -euo pipefail
while IFS= read -r -d '' path; do
    printf 'Selected: %q\n' "$path"
done < "$STRATA_ACTION_PATHS"

STRATA_ACTION_PATHS is the name of a file containing NUL-delimited paths, not a whitespace-separated list. Always quote paths; never use for path in $(cat ...) or eval. STRATA_ACTION_COUNT is invocation-local; STRATA_ACTION_POSITION is the 1-based per-item position. The invoking folder is stored byte-exactly in the file named by STRATA_ACTION_PARENT. See the environment and progress protocol for context JSON, scratch paths, and progress reporting without Python.

For an installed executable, replace [run] with this—no script file:

[run]
runtime = "command"
program = "sha256sum"
args = ["--", "{paths}"]
mode = "whole-selection"

Programs receive direct argv, not shell source: pipes, redirection, $VARIABLE, and globbing are not expanded. {paths} supplies separate arguments in whole selection mode; {path} is for per-item mode; {parent} is the invoking folder. Tokens must occupy an entire argument. Use Bash if shell syntax is needed.

Choose the mode deliberately: whole selection runs once with all paths; per item runs once for each path, with Continue/Stop controlling subsequent failures. Rename/lowercase/count-lines recipes use whole selection; conversions, checksums, and EXIF stripping use per item. Library selections apply these modes automatically, including when replacing a recipe from the other mode.

Agent handoff checklist: choose a fresh id, write the matching manifest and entrypoint, declare required tools, preserve originals/refuse overwrites, and keep the action disabled for review. Test on disposable copies through Strata's context menu, then inspect Jobs output. Exit 0 means success; nonzero means failure. Cancelling stops remaining work but does not undo filesystem changes. The full custom-actions guide documents validation, matching rules, storage, examples, and limitations.

Open Settings → Appearance from the gear menu or with Ctrl+,. Theme changes apply immediately across the interface.

Use Search settings to filter options across pages and navigate to the closest match, including keywords such as “font size.” In compact windows, the magnifying-glass button opens the search field. Clear the query or press Esc in the field to restore all settings.

On Omarchy Quattro, turn on Follow Omarchy under Settings → Appearance. Strata maps the active Omarchy palette to its semantic colors, monitors the current theme, and updates live whenever Omarchy's theme changes.

This integration supports Omarchy Quattro only. The switch is hidden when Strata cannot find a valid Quattro current-theme state; legacy Omarchy theme layouts are not supported.

Choose any included theme from Settings → Appearance: Azure Glow, Tokyo Night, Catppuccin, Everforest, Rosé Pine, or Omarchy Light. Selecting a bundled theme turns off Omarchy following and keeps that theme active across restarts.

Select Add a theme, enter a name, and choose the semantic colors for the background, surfaces, text, accent, danger, muted and highlighted elements, borders, and dimmed text. Strata previews edits live and saves completed themes under Your themes.

Custom themes are stored as shareable TOML files in ~/.config/strata/themes/. See Themes for the schema, file location, and Omarchy color mapping.

Strata defaults to the Stable channel: only final tagged releases are ever offered, and a Stable install never receives, sees, or is notified about a prerelease.

Strata checks for updates automatically by default: each time it starts, once its first window opens, and again when a window or Settings → Updates opens if no check has completed in the last 24 hours. Turning Check for updates automatically back on, or changing the channel, also runs a check. The check asks the update source for your installation: GitHub for release binaries and source builds, the AUR for AUR packages, the Omarchy package repository for Omarchy packages, or the local pacman sync database for other pacman packages. When a newer version is found, Strata also fetches that release's details from GitHub. Turning the switch off stops the automatic checks, discards the result of a check still running, hides any update notice already shown, and locks the channel. Check now still checks on demand, and the Updates page's release-notes card asks GitHub for the current version's notes when they are not already cached. Strata never downloads or installs an update without your confirmation.

To try upcoming changes early, choose a channel in Settings → Updates (the channel is locked while automatic checks are off). Preview receives curated alpha, beta, and release-candidate builds but excludes nightlies. Nightly receives every recognised prerelease, including daily development builds. The update dialog and release notes always identify the exact build kind.

When a prerelease installation selects Stable, the Updates card immediately offers the newest stable release as the channel target—even when that requires a semantic downgrade—and labels the action Return to stable. Preview and Nightly selections use the same card for ordinary forward updates, so channel changes never create a separate competing rollback card.

See Releasing for the tag grammar these channels rely on and, for maintainers, how a release candidate is cut and promoted.

Strata walks and indexes the selected directory tree on a background thread, never on GTK's UI thread. Results appear progressively during that walk. Names and relative paths are normalized once as index entries are created, and each query maintains only the best 100 fuzzy-ranked matches instead of sending an unbounded result set to the interface.

Rapid keystrokes are coalesced to the newest query. During indexing, result publication is throttled to 50 ms intervals; the UI consumes those bounded updates on its own timed loop, keeping rendering aligned with responsive frame-sized work. Exact and contiguous matches, word/path boundaries, and names rank ahead of loose path subsequences.

The deliberate tradeoff: this is fast filename and path search, not file-content or metadata search.

Files shown while browsing are untrusted. Image, camera RAW, PDF, thumbnail, and media parsing therefore runs out of process through Bubblewrap, not inside the main Strata process. Each short-lived helper receives namespace isolation, a minimal read-only runtime, exactly one canonicalized input file, private output and temporary directories, no network, and no capabilities. Memory, CPU/wall time, input, file, and parent-side output limits bound the work.

Only media helpers may receive allowlisted GPU render devices, and only for accelerated decoding; image, PDF, and thumbnail helpers receive no device mounts. Images are normalized to bounded PNG images. Media arrives incrementally as validated raw RGBA frames and fixed-format PCM: GTK presents textures and GStreamer outputs raw audio, without opening the original file or decoding a compressed clip. Four media sessions per process, bounded queues, and paused-worker cleanup limit concurrent work. Cancellation or timeout kills the process group and Bubblewrap PID namespace, tearing down descendants. Missing isolation, crashes, malformed output, timeouts, and permission failures all fail closed to a normal icon or Preview unavailable—Strata never silently retries an untrusted native parser without the sandbox.

Plain-text and source previews are different: they stay in process because they do not invoke a native format parser, and reads are capped at 1 MiB. See Preview sandbox for provider ordering, exact mounts, formats, and resource budgets.

Build requirements are the latest stable Rust toolchain, a C toolchain, pkg-config, GTK 4.12+, GtkSourceView 5, Poppler GLib, Fontconfig, and GStreamer 1.20+ (including its app/base development libraries). mise pins that toolchain locally (mise install). On Arch:

sudo pacman -S --needed base-devel bubblewrap ffmpeg ffmpegthumbnailer fontconfig \
  gstreamer gst-libav gst-plugins-base gst-plugins-good gtk4 gtksourceview5 gvfs poppler-glib
mise run start-dev        # rebuild and restart as files change
mise run dev              # build and launch the main app once
mise run chooser-dev      # build and open an isolated Save chooser with choices
mise run check            # format, compile, Clippy, tests, and policy checks

The default rar Cargo feature embeds RARLAB's non-free UnRAR implementation. Official releases and AUR builds retain RAR extraction and CBR cover previews. Packagers who cannot distribute UnRAR can exclude it with:

cargo build --locked --release --no-default-features

This build does not compile or link unrar or unrar_sys. RAR files are not offered for extraction, and CBR cover previews report that RAR support is disabled. ZIP, 7z, TAR, CBZ, and EPUB support is unchanged. Use --features rar to opt back in; --all-features also enables UnRAR. The source lockfile and license notices still describe the optional dependency; they do not mean it is linked into the feature-disabled binary. See third-party notices.

Start with CONTRIBUTING.md before opening a pull request. Deeper references:

• Keyboard navigation
• Preview panel and column layout
• 10xer mode
• Architecture principles
• Preview sandbox
• Performance baseline
• Custom actions
• Themes and Omarchy integration
• Unsafe code policy
• Releasing

This image is generated from GitHub contribution data so new contributors appear without a manual README update. Thank you to everyone who reports issues, improves the documentation, tests releases, and contributes code.

Strata is free software licensed under the MIT License. Bundled fonts, icons, and other third-party components retain their own notices in THIRD_PARTY_LICENSES.md.