ClipGloss Overlay

Small Windows-first Python desktop tool that grabs the currently selected text, translates it from English to Russian, and shows the result in a fast overlay card.

What it does

• Registers a global hotkey
• Copies the current text selection with Ctrl+C
• Sends the text to a translation model
• Shows the translated result in a custom overlay in the bottom-right corner
• Can run quietly in the background and auto-start with Windows

Project files

clipgloss-overlay/
  app.py
  background_runner.py
  requirements.txt
  .env.example
  .gitignore
  run.ps1
  run.bat
  start-background.ps1
  install-startup.ps1
  README.md

Requirements

• Windows 10 or Windows 11
• Python 3.10 or newer
• Internet access to your translation provider
• A DeepSeek API key or an OpenRouter API key

Install Python on Windows

1. Download Python 3.10+ from python.org.
2. Run the installer.
3. Enable Add python.exe to PATH.
4. Finish installation.
5. Verify in PowerShell:

py -3 --version

Setup

Clone the repository and open PowerShell in the project folder:

git clone https://github.com/nayutalienx/clipgloss-overlay.git
cd clipgloss-overlay
Copy-Item .env.example .env

Edit .env and set your preferred provider:

DeepSeek default

TRANSLATION_PROVIDER=deepseek
TRANSLATION_MODEL=deepseek-v4-flash
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://api.deepseek.com

OpenRouter optional

TRANSLATION_PROVIDER=openrouter
TRANSLATION_MODEL=deepseek/deepseek-v4-flash
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_APP_NAME=ClipGloss Overlay
OPENROUTER_SITE_URL=http://localhost

Main configuration

• TRANSLATION_PROVIDER: deepseek or openrouter
• TRANSLATION_MODEL: chat model used for translation
• SOURCE_LANGUAGE: default English
• TARGET_LANGUAGE: default Russian
• HOTKEY: global hotkey, default CTRL+3
• COPY_TRANSLATION_TO_CLIPBOARD: optional, default false
• OVERLAY_RESULT_DURATION_MS: how long the translated result stays visible
• OVERLAY_STATUS_DURATION_MS: how long short status cards stay visible
• OVERLAY_MAX_STACK: how many overlay cards can be stacked
• MAX_SELECTED_TEXT_CHARS: safety cap for selected text length

How it works

1. Select English text in any app.
2. Press Ctrl+3.
3. ClipGloss copies the selection.
4. It sends the text to the configured translation model.
5. The Russian translation appears in a custom overlay.

The overlay is not a standard Windows notification. It is a custom tkinter overlay, so it feels faster and is not queued through Windows notification center.

Run manually

PowerShell

.\run.ps1

The script creates .venv if needed, installs dependencies, and starts the app.

CMD / double-click

run.bat

Auto-start on Windows logon

Install the scheduled task:

.\install-startup.ps1

The task name is:

ClipGloss Overlay

Notes and limitations

• ClipGloss is Windows-only.
• It uses the clipboard to capture selected text.
• Text clipboard contents are restored when possible.
• If the clipboard previously held non-text data, Windows clipboard state may not be perfectly preserved.
• Very large selections are truncated before translation to control latency and cost.
• Pure code and commands are intended to stay unchanged.

Troubleshooting

Nothing happens on hotkey press

• Make sure the app is running.
• Check that the hotkey is not already used by another app.
• Try another hotkey in .env, for example CTRL+ALT+G.

Translation failed

• Check DEEPSEEK_API_KEY or OPENROUTER_API_KEY.
• Verify the selected provider/model is available on your account.
• Check the log file in logs\clipgloss.log.

The overlay does not appear

• Verify the app is running in the background.
• Check logs\clipgloss.log.
• Try running .\run.ps1 in foreground first.