Install the Shortcuts 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.
Add the Spokenly shortcut
Open this link on your iPhone to import the shortcut into your Shortcuts app:
Add Spokenly Background Dictation Shortcut
Tap Add Shortcut when prompted. The shortcut will appear in your Shortcuts library.
Assign a trigger
Choose how you want to run the shortcut: the Action Button , Back Tap , or AssistiveTouch .
Open Settings
Go to Settings on your iPhone and tap Action Button .
Select Shortcut
Swipe through the options until you see Shortcut . Tap Choose a Shortcut .
Pick the Spokenly shortcut
Search for the Spokenly background dictation shortcut and select it.
Open Accessibility settings
Go to Settings > Accessibility > Touch , then scroll down and tap Back Tap .
Choose Double Tap or Triple Tap
Tap Double Tap or Triple Tap , depending on which gesture you prefer.
Assign the shortcut
Scroll down to the Shortcuts section and select the Spokenly background dictation shortcut.
Turn on AssistiveTouch
Go to Settings > Accessibility > Touch > AssistiveTouch , then turn on AssistiveTouch .
Choose the single-tap action
Under Custom Actions , tap Single-Tap .
Assign the Spokenly shortcut
Scroll to the Shortcuts section and select the Spokenly background dictation shortcut.
Open Settings
Open Spokenly > Settings , scroll to the bottom and click Install CLI .
Enter your password
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.
Use it in your terminal
Run
spokenly transcribe
in any terminal. The installed executable is a small bash script that forwards your arguments to the locally running Spokenly app. The app then handles the request with your selected model.
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** \> **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 ```Open Spokenly and go to **Settings** .
Open the **Recording Shortcut** menu, choose **MacBook Taps** , and pick a double, triple, or four-tap gesture.
{Array.from({ length: 45 }, (_, i) => i + 1).map((n) => (
{n}
))}
↵ paragraph break · 45 words or 4 sentences
{Array.from({ length: 10 }, (_, i) => i + 46).map((n) => (
{n}
))}
Each box is a word. Whichever rule fires first triggers the break at the next sentence boundary.
-
Run:
claude mcp add spokenly -- ~/Library/Application\ Support/Spokenly/mcp-bridge.sh -
Add this line to
{"~/.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." - Restart Claude Code
-
Run:
codex mcp add spokenly --url [http://localhost:51089](http://localhost:51089) -
Add this line to
{"~/.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." - Restart Codex
Spokenly works with any tool that supports MCP. Connect using one of two transports:
-
HTTP:
Point your tool to
[http://localhost:51089](http://localhost:51089) -
stdio:
Use the bridge script at
~/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.
Any agent that can run shell commands can ask you questions without MCP through the Spokenly CLI :
spokenly ask "Which approach do you prefer?"
Install the CLI from
Spokenly > Settings > Install CLI
, then tell your agent to run
spokenly ask
whenever it needs your input. The spoken answers are printed to stdout.
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:
- Spokenly is running
- You restarted your AI tool after setup
- The MCP server entry exists in your tool's configuration
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:
- You are using the sideload version of Spokenly (not the App Store version)
- Spokenly is open and running
- No firewall is blocking local connections
Spokenly only shows integrations for tools it detects on your system. It checks for:
-
Claude Code:
Claude Desktop app or
{"~/.claude"}directory -
Codex:
Codex app or
{"~/.codex"}directory -
Cursor:
Cursor app or
{"~/.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 Code:
Run
claude mcp remove spokenlyand remove the Spokenly line from{"~/.claude/CLAUDE.md"} -
Codex:
Run
codex mcp remove spokenlyand remove the Spokenly line from{"~/.codex/AGENTS.md"} -
Cursor:
Remove the
"spokenly"entry from{"~/.cursor/mcp.json"}and remove the Spokenly rule from Cursor User Rules
Open Agentic Actions
Create or edit a mode, then click the lightning bolt button shown above.
Turn on the actions you want
Toggle on each action this mode should run. Enable only what you need; fewer actions means faster, more predictable runs.
Save and test
Save the mode and use **Test** to confirm it runs the action on your dictation.