# 028 Agents 515671bb

> Supervertaler - AI Agent Documentation (Compact)

- Skill: `tools-only/028-agents-515671bb` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/028-agents-515671bb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/028-agents-515671bb/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/028-agents-515671bb

---

# Supervertaler - AI Agent Documentation (Compact)

> **Purpose:** Fast, reliable handoff when context is low or chats reset.
> **Last Updated:** February 9, 2026 | **Version:** v1.9.246

---

## ⚡ 60-Second Resume Checklist

1. Read `CHANGELOG.md` top entry (latest release context).
2. Check `git status --short` (do not revert unrelated user changes).
3. Confirm version in `pyproject.toml`.
4. Confirm unified settings in `settings/settings.json`.
5. If deeper context is needed, open:
   - `docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md`

---

## 🎯 Current State

- **Current version:** `v1.9.246`
- **Main app:** `Supervertaler.py` (large monolithic PyQt6 file)
- **Latest major completed work:**
  - Cross-platform support: macOS/Linux via `modules/platform_helpers.py` (v1.9.246)
  - Native global hotkey system replacing AHK-only approach (v1.9.246)
  - Unified settings system in `settings/settings.json`
  - Inline API key editing in Settings UI
  - One-time migration from legacy settings files (`.migrated`)
  - Custom OpenAI-compatible provider (`custom_openai`)

---

## 📁 Key Paths (Source of Truth)

- Main app: `Supervertaler.py`
- Modules: `modules/`
- Platform helpers: `modules/platform_helpers.py`
- Tests: `tests/`
- Changelog: `CHANGELOG.md`
- Version source: `pyproject.toml`
- Dependencies: `requirements.txt` (includes `pynput>=1.7.6`)
- Website version mention: `docs/index.html`
- Unified settings: `settings/settings.json`
- AHK hotkey script (Windows fallback): `supervertaler_hotkeys.ahk`
- Archived full agent reference:
  - `docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md`

---

## 🏗️ Settings Architecture (v1.9.240+)

Primary config:
- `settings/settings.json`

Top-level sections:
- `api_keys`
- `general`
- `ui`
- `features`

Satellite files under `settings/`:
- `themes.json`
- `shortcuts.json`
- `recent_projects.json`
- `find_replace_history.json`
- `superlookup_history.json`
- `voice_commands.json`
- `model_version_cache.json`

Migration behavior:
- Legacy settings files are migrated at startup and renamed to `.migrated`.

---

## 🔑 API Keys

Primary storage:
- `settings/settings.json` under `api_keys`

Compatibility:
- Legacy `api_keys.txt` remains supported as fallback input.

Common key names:
- `openai`, `claude`, `google`, `gemini`, `custom_openai`, `deepl`, `google_translate`, `ollama_endpoint`

Notes:
- `google` and `gemini` are aliases.
- `custom_openai` supports OpenAI-compatible endpoints (endpoint/model configured in Settings > AI Settings).

---

## 🌐 Cross-Platform Architecture (v1.9.246+)

Central module: `modules/platform_helpers.py`

Constants:
- `IS_WINDOWS`, `IS_MACOS`, `IS_LINUX`

Utilities:
- `open_file(path)` / `open_folder(path)` — replaces `os.startfile()`
- `get_hidden_subprocess_flags()` — `CREATE_NO_WINDOW` on Windows, empty dict elsewhere

Global hotkeys (`GlobalHotkeyManager`):
- Windows: `RegisterHotKey` API (background thread with `GetMessageW` loop)
- macOS/Linux: pynput `GlobalHotKeys` (requires Accessibility permission on macOS)
- Callbacks do **zero work** in the background thread — only signal Qt main thread via `QMetaObject.invokeMethod`
- Main thread handles: send Cmd/Ctrl+C → wait 250ms → read clipboard → dispatch

Keystroke injection (`CrossPlatformKeySender`):
- Windows: AHK subprocess (`Send "^c"` via temp `.ahk` file), PowerShell `SendKeys` fallback
- macOS: `osascript` (`tell application "System Events" to keystroke "c" using command down`)
- Linux: pynput `Controller`

Hotkey callback flow:
```
pynput/WinAPI thread → QMetaObject.invokeMethod (QueuedConnection)
  → @pyqtSlot _handle_superlookup_hotkey (main thread)
    → CrossPlatformKeySender.send_copy()
    → QTimer.singleShot(250ms) → read clipboard → on_ahk_capture(text)
```

---

## 🍎 macOS Hotkey Status — Pending Fixes

**Working:**
- pynput `GlobalHotKeys` registers successfully (shows "Active via PYNPUT")
- Accessibility permission grant flow works
- Crash fixed (was caused by doing pyperclip/pynput work in background thread)

**Known issues:**
1. `osascript` Cmd+C deletes selected text in source app (likely stray modifier keys from hotkey)
2. Cmd+C doesn't actually copy selections — only reads existing clipboard content
3. Reliability: sometimes works, sometimes doesn't

**Planned fixes:**
- Debug `osascript` keystroke injection (may need modifier release delay before sending)
- Consider using `pbcopy` via AppleScript instead of keystroke simulation
- Change macOS shortcuts: ⌃⌥L/M → **⌃⌘L/M** (Ctrl+Cmd, user-requested — easier to reach)

---

## 🔌 LLM Providers

Supported providers:
- `openai`
- `claude`
- `gemini`
- `ollama`
- `custom_openai`

Relevant implementation files:
- `modules/llm_clients.py`
- `Supervertaler.py` (settings UI and provider wiring)

---

## 🧪 Testing Quick Start

Run:
```bash
pytest tests/
```

Manual smoke test checklist:
- Import DOCX, translate, export
- Save/load `.svproj`
- TM and termbase behavior
- AI translation with configured keys
- SDLPPX round-trip

---

## 📦 Release Checklist

1. Update version in `pyproject.toml`.
2. Update release notes in `CHANGELOG.md`.
3. Update version mention in `docs/index.html`.
4. Validate main workflows.
5. Build and upload:

```bash
python -m build
python -m twine upload dist/supervertaler-<version>*
```

Windows EXE packaging:
- `build_windows_release.ps1` (core/full)

---

## ⚠️ High-Value Pitfalls

1. `Supervertaler.py` is large: read/edit by line range, not full-file stream.
2. Qt table access: use `cellWidget()` for editors and `item()` for plain items.
3. Block signals during programmatic text updates to avoid cascades.
4. Style issues can be timing-related (hidden widgets, deferred visibility).
5. XML namespace formats (SDLXLIFF): always use namespace dicts.

---

## 📌 Active Priorities

1. **Fix macOS global hotkey Cmd+C issues** (deletes selection, doesn't copy).
2. **Make macOS shortcuts configurable** (⌃⌘L/M instead of ⌃⌥L/M).
3. **Test Linux global hotkeys** (pynput backend, untested).
4. Keep unified settings and migration stable.
5. Continue reducing monolith pressure in `Supervertaler.py`.
6. Maintain release reliability (PyPI + Windows core/full artifacts).
7. Keep this file short and operationally focused.

---

## 📚 Archived Reference

The full historical/long-form agent document is preserved at:
- `docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md`

When context is limited, use this compact file first and open the archive only when needed.