RETIX is a local-first vision CLI for agents that need to inspect screenshots, extract visible text, and verify visual claims with deterministic output. It is built around a simple idea: keep the workflow close to the codebase, keep the defaults predictable, and expose enough control for engineering use without forcing a heavier application layer.
RETIX currently provides four primary capabilities:
describefor structured screenshot analysisocrfor text extractioncheckfor YES/NO claim verification with confidencedaemonfor keeping the model warm across repeated requests
It also includes first-class project initialization, model management, and benchmarking commands so the CLI can be used both interactively and as part of automated workflows.
uv pip install retixIf you prefer standard pip, this also works:
pip install retixuv resolves this dependency graph much faster than pip in practice, especially because RETIX depends on ML packages such as torch, torchvision, mlx, and mlx-vlm.
retix setup uses uv automatically when it is available and falls back to the standard Python tooling path on bare environments.
git clone https://github.com/SNiPERxDD/retix.git
cd retix
python3 -m pip install -e .retix setup
retix describe screenshot.png
retix ocr document.png
retix check image.png "button is visible"If you run retix with no arguments, the CLI prints the help screen.
RETIX keeps the control flow simple: the CLI routes requests, the project layer resolves local state, inference runs through the model stack, and the daemon path keeps the model warm for repeated requests.
flowchart LR
U[User or Agent] --> C[retix CLI]
C --> S[setup / config]
C --> A[describe / ocr / check]
C --> M[model / bench]
C --> D[daemon]
S --> P[.retix\nconfig.yaml\nSKILL.md]
S --> H[path_utils.py\nconfig.py]
A --> I[inference.py]
I --> Z[image_preprocessing.py]
I --> G[guardrails.py]
I --> L[MLX-VLM runtime]
D --> T[daemon_server.py]
T --> L
M --> R[model_management.py]
M --> B[benchmarking.py\nbenchmark_tokens_resolution.py]
L --> O[structured output]
G --> O
This layout matches the codebase: retix/main.py owns routing, retix/project_config.py handles project-local state, retix/inference.py and retix/image_preprocessing.py own the vision path, and retix/daemon_server.py provides the warm-process mode.
retix describe <image>
retix describe <image> --prompt "focus on buttons"
retix describe <image> --jsonretix ocr <image>
retix ocr <image> --jsonretix check <image> "submit button is visible"
retix check <image> "error banner is red" --jsonretix setup
retix setup --non-interactive
retix configretix setup validates the environment, creates the local cache virtual environment under ~/.cache/retix/venv when needed, and selects a model tier based on the machine.
If uv is installed, setup uses it for dependency installation and editable installs; otherwise it falls back to the virtual environment's built-in pip path.
retix config creates the project context in .retix/ and keeps the repository ignore rules aligned with RETIX artifacts.
retix model list
retix model info
retix model switch 1.6b
retix model switch 2b
retix model switch 8b
retix model switch moeretix benchretix bench now runs with a 1024-token generation ceiling so throughput reflects real decode workload rather than preview-only output.
Benchmark output includes:
- model identity
- input and output token counts
- a full-width cyan preview panel with the generated text
The benchmark dashboard image is regenerated each run and saved to ~/.cache/retix/bench_test_image.png.
retix daemon start
retix daemon status
retix daemon stopretix daemon stop sends SIGTERM, waits for graceful shutdown, escalates to SIGKILL if necessary, and removes stale PID/socket files.
RETIX keeps project-local state in:
.retix/
SKILL.md
config.yaml
The generated skill file is designed for agent integration and uses a minimal metadata header with ID, Name, and Version.
RETIX includes two built-in optimizations that matter in practice:
- High-resolution images are automatically downscaled before inference when needed.
- The CLI uses task-specific token limits rather than one fixed ceiling for every command.
The repository also includes benchmark_tokens_resolution.py for comparing token budgets and image resolutions.
pytest testsFor the real-world image suite:
RETIX_RUN_REAL_WORLD=1 pytest tests/real_world -m real_worldIf pip install retix appears to hang while resolving torch, use uv:
uv pip install retixIn practice, uv resolves and installs RETIX far faster than pip for this dependency set.
If uv is not installed:
brew install uvIf you want to avoid the resolver entirely, install the project from source:
git clone https://github.com/SNiPERxDD/retix.git
cd retix
python3 -m pip install -e .MIT License.