Srxy

Find files by what you mean — terminal or Python.

Fuzzy, phonetic, and semantic matching across filenames, documents, photos, audio, video, and OS tags. On a desktop session, srxy opens a GUI by default; use --tui for the terminal UI or --cli for scripts and pipes.

Installation

Needs Python 3.11+. uv tool install 'srxy[semantic]' recommended; pipx install 'srxy[semantic]' also works; pipx install srxy for core-only in a venv. Windows: add [windows] for Explorer tags. macOS: system python3 may be too old — Installation.

Platform setup (ffmpeg, tesseract): docs/installation.md. Privacy / third-party notice: docs/privacy.md.

Quick start

GUI (default on a graphical session):

srxy                          # empty query/path
srxy "registry" ./src         # pre-filled; auto-starts

Walkthrough: docs/gui.md. Architecture: docs/architecture.md.

Desktop installers (Linux + macOS):

Two Linux AppImages from GitHub Releases (decompress the .xz, make executable, and run; no host libfuse2):

Default prefix: ~/Applications/srxy. The online AppImage needs a network connection on first launch (downloads uv, managed Python, and srxy into ~/.cache/srxy/online-bootstrap/); later runs reuse the cache. It vendors PATH / tesseract / ffmpeg automatically and enables smarter-search packages only when a GPU is detected — model weights download later when you use those features. No reinstall/uninstall UI on the online path (use the offline wizard or remove the prefix).

macOS installers (.dmg, offline + online) are also published in releases and install to ~/Applications/srxy by default. Windows installer is still in progress. PyPI / uv tool install remain the primary paths on every platform. Guide: docs/installers.md. Privacy / third-party notice: docs/privacy.md.

TUI:

srxy --tui
srxy --tui "registry" ./src
srxy --tui "transform" ./docs --ocr

Live scan progress, sortable results, preview pane, option chips, clipboard copy. Full walkthrough: docs/tui.md.

Plain CLI:

srxy "registry" ./src --cli
srxy "revenue" ./docs --json
srxy "dog at the beach" ~/Pictures --semantic-image --content-only
srxy "revenue" ./docs --semantic-all --content-only

Boolean queries (|, &), scope flags, format table: docs/cli.md.

Python:

from pathlib import Path
from srxy import magic_file_search, magic_search

magic_file_search(Path("./src"), "registry", threshold=0.3)
magic_search([{"name": "salad"}], "salat", fields=["name"])

API reference: docs/python-api.md · docs/api-reference.md.

Documentation

Development

Requires uv.

uv sync --extra semantic
uv run task checks-fix
uv run task checks              # day-to-day
uv run task checks-full         # before release
uv run task checks-full-cpu     # + forced-CPU transcribe matrix

CI runs unit tests only (unit marker, excluding semantic and transcribe). Details: docs/development.md.

Try fixtures: srxy "axolotl" ./tests/fixtures/file_search

License

MIT — see LICENSE.