Tidytalk user guide

Install and set up

Tidytalk needs macOS 26 or later on a Mac with Apple silicon.

1. Download the latest Tidytalk-x.y.z.dmg from GitHub Releases, open it, and drag Tidytalk into the Applications folder.
2. The app isn't notarized by Apple yet, so macOS blocks it the first time. Open System Settings › Privacy & Security and click "Open Anyway" at the bottom, or run this in Terminal:

   xattr -dr com.apple.quarantine /Applications/Tidytalk.app

3. Follow the setup guide that opens:
   • Allow Microphone so Tidytalk can record.
   • Allow Accessibility so it can detect the shortcut and paste text at your cursor.
   • Set Up AI: enter an OpenAI-compatible endpoint, API key, and model. DeepSeek is the default. You can skip this and get the raw transcript instead.
   • Download Speech Model: about 240 MB, once. After that, recognition works offline.

Tidytalk lives in the menu bar. It only appears in the Dock while its setup or settings window is open. Open the menu bar icon for settings, recent results, and the output language.

Hold to talk

1. Put your cursor in any text field.
2. Hold Option + Command and speak. A glass indicator appears at the bottom of the screen and moves with your voice.
3. Let go. After a moment, the tidied text appears at your cursor.

• Recording starts after you hold the keys for about 0.4 seconds, so ordinary shortcuts such as Option + Command + a letter don't trigger it.
• Press another key, click the mouse, or press Esc while holding to cancel.
• One recording can be up to about 2 minutes. Recordings shorter than half a second are ignored.
• Change the shortcut in Settings › Recording. You can choose Control, Option, Command, Fn (🌐), Right Option, or Right Command. If you choose Fn, set "Press 🌐 key to" to "Do Nothing" in System Settings › Keyboard, or macOS opens emoji or Dictation at the same time.
• Live text appears under the indicator while you speak. It's only a preview: the final result is recognized and tidied after you let go.
• If there's nowhere to type, for example the focus is on the desktop or a web page, the result is copied to the clipboard instead of pasted.
• Your clipboard is restored after pasting, including images, files, and rich text.

Hands-free recording

Double-tap the shortcut to start recording without holding the keys, which is handy for longer thoughts. Press the shortcut once more to finish, or Esc to cancel. Typing and clicking don't interrupt a hands-free recording. You can turn this off in Settings › Recording.

Rewrite selected text

Select some text, hold Right Option, and say how to change it, such as "make it more formal", "shorten this to one sentence", or "translate to English". When you let go, the selection is replaced with the rewrite.

• This needs an AI service. The selected text and your instruction are sent to it.
• If nothing is selected, Tidytalk asks you to select text first. If the rewrite fails, your text isn't changed.
• Change or turn off the rewrite shortcut in Settings › Recording.

How tidying works

Tidying only removes and corrects. It doesn't change what you said:

• Filler words such as "um", "uh", and "like" (and 嗯、那个、就是说 in Chinese) are removed.
• Repeated words and slips are removed. When you correct yourself, only the corrected version is kept.
• Punctuation is added, and long speech is split into sentences.
• It never summarizes or adds content. English words and technical terms inside Chinese speech are kept as they are.
• Text that sounds like a command, such as "write me an email", is tidied into text, not carried out.

Turn off "Tidy up text" in Settings › Set Up AI to paste the raw transcript. Tidytalk then works fully offline. If the AI service is slow, unreachable, or returns something unexpected, Tidytalk pastes the raw transcript and tells you.

Cleanup strength and mode

Both are in Settings › Set Up AI › Tidying.

Output language

By default the output is in the language you spoke. Choose another output language and the text is translated as it's tidied, so you can speak Chinese and paste an English email. Tidytalk can translate into English, Simplified Chinese, Traditional Chinese, Japanese, Korean, French, German, and Spanish.

• Change it in Settings › Set Up AI › Tidying, or quickly from the "Output Language" submenu in the menu bar.
• Translation and tidying happen in one request, so it's about as fast as tidying alone. Your vocabulary and mode still apply.
• Translation needs "Tidy up text" turned on. If the request fails, the original text is pasted.

See Dictate and translate for examples.

Local AI models

Tidytalk talks to AI services with the OpenAI-compatible protocol, so it also works with models running on your Mac. Then your text never leaves the computer.

1. Install Ollama and download a model, for example ollama pull qwen2.5:7b. Or download and load a model in LM Studio and start its local server.
2. In Settings › Set Up AI, click "Presets", choose "Ollama (local)" or "LM Studio (local)", confirm the model name, and save. Local models don't need an API key, and the timeout is raised to 60 seconds.
3. Click "Test Connection".

Results depend on the model size. Small models follow "tidy, don't answer" and custom rules less reliably than cloud models, so a model around 7B or larger is recommended. See Private and offline dictation for details.

Vocabulary

All of these are in Settings › Vocabulary.

Common words

List names, products, and terms you use, one per line. These are the words speech recognition gets wrong most often. They're added to the AI prompt so similar-sounding mistakes are corrected to your spelling. Requires "Tidy up text".

Replacements

Always replace one spelling with another, for example "cloud" with "Claude". English matching ignores case and only matches whole words. Replacements run on your Mac, even with tidying off. From "Recent" in the menu bar, choose a result and "Add to Vocabulary…" to add a misheard word directly.

Snippets

Say only a phrase such as "my email" to insert a full email address or a canned reply. The snippet is used only when the whole recording is that phrase, never when it appears inside a sentence.

Custom rules

Write your own rules, one per line, such as "Write amounts as digits" or "Write the product name as Tidytalk". Tidying and voice rewrite follow them. Rules only affect how things are written; they never make the AI add content. Up to 20 rules.

Chinese–English spacing

Tidytalk adds spaces between Chinese and English or numbers, uses full-width punctuation after Chinese, and converts full-width letters and digits to half-width. Decimal points, file names, and URLs aren't affected. This runs on your Mac and can be turned off in Settings › General.

Recent results

Your last 20 results are kept in memory. From "Recent" in the menu bar you can paste or copy one again, copy the raw transcript, re-tidy it with another mode or language and paste it into the current text field, or add a misheard word to your vocabulary. Nothing is written to disk, and the list is cleared when you quit.

Supported languages

You don't choose a language before speaking. Tidytalk detects it automatically and supports:

• Mandarin Chinese, including English words and technical terms mixed in
• English
• Japanese
• Korean
• Cantonese (written in Simplified Chinese, keeping Cantonese wording)

Other spoken languages aren't supported yet. To write in French, German, or Spanish, speak Chinese or English and set the output language. The interface is available in English and Simplified Chinese and follows your system language.

Troubleshooting

Accessibility still shows as not allowed

If Tidytalk is turned on in System Settings but still shows as not allowed, the list probably has an entry from an older version. In System Settings › Privacy & Security › Accessibility, select Tidytalk, click "−" to remove it, then click "Allow" in Tidytalk to add it again. Or run:

tccutil reset Accessibility app.tidytalk.Tidytalk

All settings are stored in ~/.tidytalk.json, which you can edit directly. See the configuration reference.

Uninstall

Dragging Tidytalk to the Trash removes only the app. The speech model, settings, and permission records stay on your Mac. To remove everything, quit Tidytalk (turn off "Open at login" first if you enabled it), move the app to the Trash, and run:

rm -rf ~/Library/Application\ Support/Tidytalk
rm -f ~/.tidytalk.json
rm -rf ~/Library/Caches/app.tidytalk.Tidytalk ~/Library/HTTPStorages/app.tidytalk.Tidytalk
defaults delete app.tidytalk.Tidytalk
tccutil reset All app.tidytalk.Tidytalk

These remove the speech model (about 240 MB), your settings including your API key, network caches, preferences, and microphone and accessibility permissions. Keep ~/.tidytalk.json if you plan to reinstall and want your settings back.