# tacheles

> Push-to-talk dictation for Linux that knows your technical vocabulary and learns the terms it
> gets wrong. Records the microphone on a hotkey, transcribes with the OpenAI API or a local
> Whisper server, corrects the result against your own word list, and puts the text on the
> clipboard.

tacheles exists because the bottleneck in working with coding agents is not typing speed, it is
the reluctance to explain something properly. Writing four paragraphs of context has a cost, so
people write three lines instead, the agent guesses, and the work comes back wrong. Speaking costs
almost nothing, so the whole explanation gets given the first time.

The obstacle was that general speech models mangle developer speech: "fast API" for FastAPI, "red
is" for Redis, "P and PM" for pnpm. Fixing the transcript costs more than typing would have, so
the friction just moves. tacheles sends a vocabulary list with each request, corrects the returned
text against that same list, and permanently learns any correction the user confirms.

Platform: Linux. First-class on GNOME/Wayland (hotkey installer and a top-bar indicator);
the core works on X11, KDE, sway and Hyprland with a manually bound hotkey.
Language: Python 3.11+. Single runtime dependency: the `openai` SDK.
Licence: MIT.

## What makes it different from other dictation tools

- **Vocabulary-aware.** Terms are sent as API `keywords`, not guessed phonetically.
- **Self-correcting.** A deterministic pass fixes compound splits ("web socket" to WebSocket) and
  casing after transcription, at no cost and no latency.
- **Learns.** `tacheles fix <misheard> <correct>` teaches a mapping that is then applied
  deterministically forever. Uncertain corrections are surfaced for review, never applied silently.
- **Multilingual mid-sentence.** English, German and Russian in one utterance, each kept in its own
  script.
- **Runs locally if you want.** Point it at whisper.cpp, faster-whisper or Speaches and no audio
  leaves the machine; the vocabulary and learning layers are unchanged.
- **Never rewrites a real word unattended.** Corrections are checked against hunspell dictionaries
  for every declared language first.

## Docs

- [README](https://github.com/ErikEremenko/tacheles/blob/main/README.md): install, usage, configuration
- [Credentials](https://github.com/ErikEremenko/tacheles/blob/main/docs/CREDENTIALS.md): API key handling, secret managers, and how to verify nothing is sent anywhere else
- [Local inference](https://github.com/ErikEremenko/tacheles/blob/main/docs/LOCAL.md): running without the cloud
- [Hotkeys](https://github.com/ErikEremenko/tacheles/blob/main/docs/HOTKEYS.md): binding on non-GNOME desktops
- [FAQ](https://github.com/ErikEremenko/tacheles/blob/main/docs/FAQ.md)

## Install

```
git clone https://github.com/ErikEremenko/tacheles && cd tacheles && ./install.sh
tacheles auth login
tacheles doctor
```

## Not what you are looking for if

- You want dictation on macOS or Windows. This is Linux-only.
- You want a GUI application. It is a CLI plus an optional GNOME extension.
- You want real-time captions as you speak. It is push-to-talk: record, stop, transcribe.
