Use your Spokenly shortcut to start listening.
Talk in full sentences; punctuation and formatting are handled for you.
Let go and your words appear in the active app automatically.
Install a local model like NVIDIA Parakeet or Whisper and run it on your Mac.
Turn on Local Only Mode in Spokenly to block all network access.
Start dictating. Your audio and text never leave your device.
Go to the Contact page.
Enter your message and email, then select Send Message .
Select Send Logs to include technical logs with your message.
If you can’t find the email, contact us through the app.
Make sure the Shortcuts app is installed on your iPhone. It comes pre-installed on iOS 13 and later, but if you removed it, re-download it from the App Store.
Open this link on your iPhone to import the shortcut into your Shortcuts app:
Add Spokenly Clipboard Dictation Shortcut
Tap Add Shortcut when prompted. The shortcut will appear in your Shortcuts library.
Choose how you want to launch the shortcut: via the Action Button or Back Tap .
Go to Settings on your iPhone and tap Action Button .
Swipe through the options until you see Shortcut . Tap Choose a Shortcut .
Search for the Spokenly clipboard dictation shortcut and select it.
Go to Settings > Accessibility > Touch , then scroll down and tap Back Tap .
Tap Double Tap or Triple Tap , depending on which gesture you prefer.
Scroll down to the Shortcuts section and select the Spokenly clipboard dictation shortcut.
Open Spokenly > General Settings , scroll to the bottom and click Install CLI .
macOS will ask for your password to create a symlink in
/usr/local/bin/
. This is a standard system directory for command-line tools. Spokenly does not gain any elevated privileges; the prompt is only for placing the shortcut there.
Run
spokenly transcribe
in any terminal. The installed executable is a small bash script that forwards your arguments to the locally running Spokenly app. All transcription happens inside the app itself.
Open Spokenly.
Go to Modes .
Right-click the mode you want to use.
Open the Deeplink submenu, then choose Copy Mode ID .
Open Terminal and remap the dictation key to **F5** :
```sh hidutil property --set '{"UserKeyMapping":[{ "HIDKeyboardModifierMappingSrc":0xC000000CF, "HIDKeyboardModifierMappingDst":0x70000003E }]}' ```In Spokenly, go to **Settings** \> **General** \> **Recording Shortcut** and record **F5** by pressing the dictation key.
Create the file `~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist` with this content:
```xmlLoad it:
```sh launchctl bootstrap gui/$(id -u) \ ~/Library/LaunchAgents/app.spokenly.KeyRemapping.plist ```Each box is a word. Whichever rule fires first triggers the break at the next sentence boundary.
claude mcp add spokenly -- ~/Library/Application\ Support/Spokenly/mcp-bridge.sh
{"~/.claude/CLAUDE.md"}
:
"ALWAYS ask questions via mcp__spokenly__ask_user_dictation (load via ToolSearch if needed), never as plain text. I use Spokenly for voice input."
codex mcp add spokenly --url [http://localhost:51089](http://localhost:51089)
{"~/.codex/AGENTS.md"}
:
"ALWAYS ask questions via the ask_user_dictation tool from the spokenly MCP server, never as plain text. I use Spokenly for voice input."
Spokenly works with any tool that supports MCP. Connect using one of two transports:
[http://localhost:51089](http://localhost:51089)
~/Library/Application\ Support/Spokenly/mcp-bridge.sh
Then add an instruction to your tool's system prompt or config file telling it to always use the
ask_user_dictation
tool for user input.
If the setup looks correct but the MCP tool still does not work, paste this prompt into your AI tool to run an automated check:
{`Help me diagnose why the Spokenly MCP server is not working. Check these in order:
1. Is the MCP server registered? For Claude Code, run: claude mcp list. For Codex, run: codex mcp list. For Cursor, read ~/.cursor/mcp.json.
2. Is the Spokenly HTTP server responding? Run: curl -s http://localhost:51089
3. For Claude Code stdio transport: check if the bridge script exists at ~/Library/Application Support/Spokenly/mcp-bridge.sh and is executable (chmod +x). The bridge reads JSON-RPC from stdin, forwards it to http://localhost:51089 via curl, and prints the response. Try running it manually: echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | ~/Library/Application\\ Support/Spokenly/mcp-bridge.sh
4. For Codex/Cursor HTTP transport: the MCP URL should be http://localhost:51089
5. Is Spokenly running? Check: pgrep -f Spokenly
Report what you found and suggest fixes.`}
Make sure the setup instruction was fully executed. Check that:
If the MCP server is connected but the agent still asks questions as plain text, update your instructions file with a stronger prompt. Open
{"~/.claude/CLAUDE.md"}
(Claude Code) or
{"~/.codex/AGENTS.md"}
(Codex) and replace the Spokenly line with:
NEVER ask questions to the user via plain text output. ALWAYS use mcp__spokenly__ask_user_dictation for any question or confirmation. Load it via ToolSearch at the start of every conversation. This is the user's preferred default way to communicate.
For Cursor, update your global User Rules with the same text, replacing the tool name with
ask_user_dictation
from the
spokenly
MCP server.
Spokenly's MCP server runs on
localhost:51089
. Make sure:
Spokenly only shows integrations for tools it detects on your system. It checks for:
{"~/.claude"}
directory
{"~/.codex"}
directory
{"~/.cursor"}
directory
If you have the CLI tool installed but not the desktop app, the directory check should still detect it.
To remove Spokenly's MCP integration:
claude mcp remove spokenly
and remove the Spokenly line from
{"~/.claude/CLAUDE.md"}
codex mcp remove spokenly
and remove the Spokenly line from
{"~/.codex/AGENTS.md"}
"spokenly"
entry from
{"~/.cursor/mcp.json"}
and remove the Spokenly rule from Cursor User Rules
Create or edit a mode, then click the lightning bolt button shown above.
Toggle on each action this mode should run. Enable only what you need; fewer actions means faster, more predictable runs.
Save the mode and use **Test** to confirm it runs the action on your dictation.