A small Python utility that listens for a global hotkey (Ctrl+Shift+C by default), captures code from the clipboard or a screenshot, sends it to a local Ollama model, and shows an explanation via notification, popup, or terminal.

Privacy: Everything runs locally. No external APIs are called. Ollama must be installed and the model available locally.

• Global hotkey using pynput.
• Capture code from clipboard, or screenshot (with optional OCR via pytesseract).
• Local LLM via ollama Python package.
• Customizable system prompt and user intent (explain, optimize, tests, security, etc.).
• Output via plyer notification, tkinter popup, or terminal.
• Configurable via JSON and/or CLI flags.

• Python 3.9+
• Ollama installed and running locally with a pulled model (e.g., devflow-gpt-fast:latest).
• Windows requires permissions for global hotkeys; run in a terminal.

Install deps:

python -m venv .venv ; .\.venv\Scripts\Activate.ps1 ; pip install -r requirements.txt

# Copy some code to clipboard, then run:
python code_explainer.py --print

Press Ctrl+Shift+C to trigger. Explanation will print in the terminal (or notification/popup based on config).

Launch the built-in Tkinter interface:

python code_explainer.py --gui

From the GUI you can:

• Start/stop the global hotkey listener.
• Switch between Clipboard and Screenshot modes, toggle OCR and region selection.
• Choose output method (GUI-only display, or also trigger plyer/tkinter/terminal).
• Pick/change the local Ollama model and prompt/intent.
• Manually run “Explain Clipboard” or “Explain Screenshot” without hotkeys.

Copy config.example.json to config.json and edit:

{
  "mode": "clipboard",
  "notify": "plyer",
  "ollama": { "model": "devflow-gpt-fast:latest", "timeout_seconds": 60 },
  "prompt": {
    "system": "You are a senior software engineer...",
    "user_intent": "explain"
  },
  "hotkey": "<ctrl>+<shift>+c",
  "screenshot": { "ocr": false, "region_select": true },
  "cli": { "print_to_terminal": false }
}

Run with config:

python code_explainer.py --config config.json

• Force screenshot mode with OCR and tkinter popup:

python code_explainer.py --mode screenshot --ocr --notify tkinter --print

• Use a different model and intent:

python code_explainer.py --model devflow-gpt:latest --intent tests --print

• If screenshot OCR is enabled, you need pytesseract and Tesseract installed on your system.
• If OCR is disabled, the script will send a generic hint when using screenshots.
• If plyer notifications are truncated, use --notify tkinter or --print.

• "Missing dependencies" -> install with pip install -r requirements.txt.
• "Model error" -> ensure Ollama service is running and model exists (ollama list).
• Hotkey not triggering -> check for conflicts with other apps; try a different hotkey via --hotkey.
• Clipboard empty -> copy text first or switch to screenshot mode.