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+. Prefer uv (pipx install … is fine too).

Desktop installers (preferred)

Grab the latest installers from GitHub Releases — AppImages, DMGs, and the Windows .exe are all there. You can also buy the installers from the official site (includes a signed macOS build). Details: docs/installers.md.

Terminal install (PyPI release)

[semantic] adds smarter search (PyTorch, CLIP, Whisper) and is intended for machines with a GPU — CPU-only semantic is too slow for most users. On Windows, pywin32 (Explorer tags) is included automatically. PyPI’s Windows torch is CPU-only, so the GPU line uses --with/--index to pull CUDA wheels. macOS system python3 may be too old — Installation.

Latest development version

Install the current develop branch as a standalone tool (same layout as PyPI, but built from git):

uv tool install "srxy @ git+https://github.com/illescasDaniel/srxy@develop"
uv tool install "srxy[semantic] @ git+https://github.com/illescasDaniel/srxy@develop"   # GPU
uv tool install --force "srxy @ git+https://github.com/illescasDaniel/srxy@develop"     # update in place

On Windows + NVIDIA, add the CUDA wheels (checkout [tool.uv.sources] does not apply to uv tool install):

uv tool install "srxy[semantic] @ git+https://github.com/illescasDaniel/srxy@develop" \
  --with torch --with torchvision --with torchaudio \
  --index https://download.pytorch.org/whl/cu130

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

macOS	Linux	Windows

Walkthrough: docs/gui.md. Architecture: docs/architecture.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. First-time checkout setup uses the platform-aware sync script (stdlib-only — no project venv required):

uv run --no-project python scripts/dev/sync.py                     # dev env (default-groups = ["dev"])
uv run --no-project python scripts/dev/sync.py --group uploader    # dev + twine (PyPI upload)
uv run --no-project python scripts/dev/sync.py --no-default-groups # runtime only, no pytest/ruff

Wrappers: ./scripts/dev/sync.sh (Unix) or powershell -File .\scripts\dev\sync.ps1 (Windows).

Once .venv exists, thin Taskipy aliases also work:

uv run task sync-dev
uv run task sync-uploader
uv run task checks-fix
uv run task checks              # day-to-day (auto-scope)
uv run task checks-gui          # core+gui when working on the GUI
uv run task checks-full         # before release
uv run task checks-full-cpu     # + forced-CPU transcribe matrix

CI runs core+gui+tui buckets (no heavy/real-model suite). Details: docs/development.md.

Agent memory bank (per-branch project state): memory/README.md.

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

License

MIT — see LICENSE.