Everything you need to install Telmur, learn the four modes, and tune it to the way you actually work. Read top-to-bottom on first install, or jump to the section you need.
Applications folder.Telmur is a Developer-ID-signed, notarized native macOS app — about 43 MB. It runs on macOS 13 (Ventura) or later, on both Apple Silicon and Intel Macs.
On first launch the app appears in the macOS menu bar (look for the lime-tinted Telmur icon next to the clock). There is no Dock icon and no main window — Telmur lives in the menu bar and pops a small overlay when you record.
A brief setup flow walks you through the system permissions Telmur needs. Grant them, click Relaunch, and you're ready to record.
Telmur needs three permissions from macOS. The setup window opens System Settings at the right pane for each one.
| Permission | Why |
|---|---|
| Microphone | To capture your voice while the hotkey is held. |
| Accessibility | To listen for the global hotkey from any app, and to paste the transcribed text where your cursor is. |
| Screen Recording | To capture the frontmost window as visual context (Assistant and Agent modes only — never the full desktop, never silently). |
Screen Recording activates fully only after a relaunch — that's a macOS requirement. The setup window handles the relaunch for you.
You can revoke any of these at any time in System Settings → Privacy & Security. Telmur will tell you what's missing the next time it needs the permission.
While you're recording, a small floating overlay appears near the bottom of the screen. It shows:
Press Esc at any time. Cancelling discards both the audio and any in-flight processing — nothing is pasted, nothing is sent.
For modes that produce a generated reply (Assistant, Agent, Rewrite), the result streams in word by word as it's produced. You'll see the overlay or chat panel update live — no waiting for the full response.
Telmur has four modes, switchable from the menu bar's Mode submenu. The active mode applies to whichever hotkey you press next.
Speak, paste. The transcript is cleaned up — capitalisation, punctuation, paragraph breaks where the topic shifts. Names and jargon visible on your screen are spelled correctly without you fixing them. Optional: set a target language to translate as you speak.
Telmur captures the frontmost window and uses it as visual context. Speak the gist of what you want to say, and an LLM composes a full reply in the tone of the surrounding conversation. Auto-detects chat apps (Slack, Telegram, WhatsApp) and adapts.
Opens a floating chat panel. Each turn captures a fresh screenshot, so the AI keeps up with your IDE, terminal, design draft, or whatever you're looking at. Press the hotkey again to add another turn; close the panel or press Esc to end the session. Replies are copied to the clipboard, not auto-pasted.
Highlight any text in any app. Press the hotkey, dictate the change ("make it shorter", "fix the grammar", "translate to English") — the selected text is replaced with the rewritten version. Works wherever paste works.
Click the menu-bar icon → Mode → pick one. The choice persists across launches. There is no per-hotkey mode binding — all nine hotkeys behave the same, in whatever mode is currently selected.
| Shortcut | Action |
|---|---|
| ⇧⌘1–9 | Start recording (hold) or toggle recording (quick-press). The digit selects which numbered prompt slot to use — see §8 for what that means. |
| Esc | Cancel an in-progress recording, dismiss the overlay, or close the Agent chat session. |
The combination of digit (prompt slot) plus the currently-selected mode is what determines what Telmur actually does. For most people, sticking to one digit (usually ⇧⌘1) and changing the mode in the menu when needed is the simplest workflow.
Click the Telmur icon in the menu bar to open its menu. Here's what each item controls:
| Item | What it does |
|---|---|
| Mode | Switch between Dictation / Assistant / Agent / Rewrite. |
| Prompt style | Auto, Universal, or Chat. "Auto" picks Chat when the frontmost app is a messaging app (Slack, Telegram, WhatsApp), otherwise Universal. |
| Language | Auto (transcribe in whatever you spoke) or a specific target
language (translate as you speak). Add new languages by dropping a
lang_*.md file in the prompts folder. |
| Model | Fast, Normal, or Pro. Faster models give you the result sooner; Pro is more thorough on harder reasoning. Pick whichever fits the task. |
| Clipboard Context | When on, the current clipboard contents are sent alongside the transcription as additional context. Copy a code snippet or a URL before speaking — the AI will use it. |
| Edit Usecase Prompt | Opens the prompt file for the current usecase in TextEdit. Saves take effect on the next recording. |
| Edit Language Prompt | Same, but for the language-specific instructions. |
| Edit Vocabulary | Opens vocabulary.md in TextEdit — see
§9. |
| Launch at Login | Toggle whether Telmur starts automatically when you log in. |
| Show Logs in Finder | Opens the log folder. Useful if something goes wrong — see §12. |
| Verbose Logging | Toggle DEBUG-level detail in the logs. Persists across launches. Leave off unless you're chasing a bug. |
| Quit | Exit Telmur. Hotkeys stop working until you launch it again. |
Every system prompt Telmur uses is a plain Markdown file you can edit. On first launch the bundled defaults are copied into your editable folder; saves you make there don't get overwritten by app updates.
Open them via the menu bar (Edit Usecase Prompt / Edit Language Prompt) — both open in TextEdit. The change picks up on the next recording, no restart.
universal.md — the default Assistant prompt.
What you'd want for general "answer this" / "draft a reply" use.chat.md — tuned for messaging apps. Shorter,
casual, matches the channel's tone.rewrite.md — instructions for Rewrite mode.lang_auto.md — respond in whatever language you
spoke.lang_en.md — always respond in English.The digit on each hotkey (⇧⌘1 vs. ⇧⌘2, etc.) selects a prompt slot. You can have a different prompt template per slot — for example, slot 1 for general assistance, slot 2 for code review, slot 3 for translation. See the comments inside the prompt files for how to wire additional slots.
Speech recognition stumbles on names, brand-specific jargon, and unusual words.
Telmur lets you maintain a vocabulary.md of your specific terms —
the transcriber biases toward them when it's uncertain.
Open it from the menu bar (Edit Vocabulary). The file is plain Markdown — headings, bullets, and HTML comments are ignored; plain lines and bullet items count as terms. Example:
# vocabulary.md PostgreSQL FFmpeg TypeScript Anastasiia Kubernetes
Click the microphone name in the bottom-right corner of the recording overlay to switch input devices. Telmur sees every device CoreAudio sees — built-in, AirPods, USB interface, virtual mics. Your selection persists between sessions.
Set the language from the menu bar's Language submenu. The default is Auto — Telmur transcribes whatever you spoke. Pick a specific language to enable on-the-fly translation: speak in any language, get the transcript in the one you chose.
To add a target language not in the menu, drop a lang_<code>.md
file (where <code> is a BCP-47 tag like de,
ja, pt-BR) into the prompts folder. The menu picks it
up on next launch.
vocabulary.md once —
problem solved across every future recording.
Menu bar → Show Logs in Finder opens the log folder. Two files live there:
telmur.log — everything (or DEBUG when verbose is on).
Rotates at 5 MB, keeps three backups.telmur.error.log — only warnings and errors. The first place
to look when something misbehaves.
Toggle Verbose Logging in the menu before reproducing a bug if
you want more detail in telmur.log. Turn it back off when you're
done — it makes the file grow faster.
Email hi@telmur.com with a description of
what you did, what you expected, and what happened instead. Attaching the last
few hundred lines of telmur.error.log usually saves a round-trip.
Telmur.app from /Applications to the
Trash.~/Library/Application Support/Telmur/.~/Library/Logs/Telmur/.