fix(ocr): allow configuring tesseract path

.env.example

@@ -14,3 +14,4 @@ CLICKTHROUGH_EXEC_DEFAULT_SHELL=powershell
 CLICKTHROUGH_EXEC_TIMEOUT_S=30
 CLICKTHROUGH_EXEC_MAX_TIMEOUT_S=120
 CLICKTHROUGH_EXEC_MAX_OUTPUT_CHARS=20000
+# CLICKTHROUGH_TESSERACT_CMD=/usr/bin/tesseract

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul W.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -24,7 +24,7 @@ CLICKTHROUGH_TOKEN=change-me python -m server.app
 
 Server defaults to `127.0.0.1:8123`.
 
-For OCR support, install the native `tesseract` binary on the host (in addition to Python deps).
+For OCR support, install the native `tesseract` binary on the host (in addition to Python deps), or point `CLICKTHROUGH_TESSERACT_CMD` at the executable if it lives somewhere weird.
 
 `python-dotenv` is enabled, so values from a repo-root `.env` file are loaded automatically.
 
@@ -58,6 +58,7 @@ Environment variables:
 - `CLICKTHROUGH_EXEC_TIMEOUT_S` (default `30`)
 - `CLICKTHROUGH_EXEC_MAX_TIMEOUT_S` (default `120`)
 - `CLICKTHROUGH_EXEC_MAX_OUTPUT_CHARS` (default `20000`)
+- `CLICKTHROUGH_TESSERACT_CMD` (optional path to the `tesseract` executable)
 
 ## Gitea CI
 

docs/API.md

@@ -213,6 +213,7 @@ Notes:
 - Output is deterministic JSON (stable ordering by top-to-bottom, then left-to-right).
 - `bbox` coordinates are in global screen space for `screen`/`region`, and image-local for `image`.
 - Requires `tesseract` executable plus Python package `pytesseract`.
+- If `tesseract` is not on `PATH`, set `CLICKTHROUGH_TESSERACT_CMD` to the full executable path.
 
 ## `POST /exec`
 

server/app.py

@@ -51,6 +51,7 @@ SETTINGS = {
     "exec_max_timeout_s": int(os.getenv("CLICKTHROUGH_EXEC_MAX_TIMEOUT_S", "120")),
     "exec_max_output_chars": int(os.getenv("CLICKTHROUGH_EXEC_MAX_OUTPUT_CHARS", "20000")),
     "exec_secret": os.getenv("CLICKTHROUGH_EXEC_SECRET", "").strip(),
+    "tesseract_cmd": os.getenv("CLICKTHROUGH_TESSERACT_CMD", "").strip(),
 }
 
 
@@ -301,6 +302,10 @@ def _import_ocr_libs():
         import pytesseract
         from pytesseract import Output
 
+        tesseract_cmd = SETTINGS["tesseract_cmd"]
+        if tesseract_cmd:
+            pytesseract.pytesseract.tesseract_cmd = tesseract_cmd
+
         return pytesseract, Output
     except Exception as exc:
         raise HTTPException(status_code=500, detail=f"ocr backend unavailable: {exc}") from exc