Give Claude Code a Voice in Cursor

Set up a hands-free voice conversation loop with Claude Code in Cursor.

Introduction

30 Second Summary

Talking is faster than typing. When you're brainstorming with an AI assistant, the friction of translating your thoughts into typed text slows you down and breaks your flow.

In this project, you will set up a hands-free voice conversation loop with Claude Code inside Cursor. You will speak your prompts, hear your Mac announce when Claude is ready, and listen to responses read aloud.

What You'll Build

You speak a question, Claude thinks, your Mac says "Ready" out loud, you select the response and hear it read back, then you dictate your next message. No typing required for the entire conversation.

By the end of this project, you'll have:

A voice-in workflow where you press a shortcut, speak your prompt, and it types directly into Claude Code's chat panel.
A voice notification powered by a Claude Code hook that makes your Mac announce out loud when Claude finishes thinking.
A voice-out workflow where you select Claude's response, press a shortcut, and hear your Mac read it aloud.
Secret Mission: Make Claude automatically read its own response out loud by configuring a Stop hook that pipes text to the say command.

Are there any prerequisites?

You need a Mac with a working microphone, Cursor installed, and Claude Code working inside Cursor. This project walks you through enabling macOS Dictation and Speak Selection from scratch.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters. This step is your moment to commit to the goal before any configuration begins.

Set Up Voice Input with macOS Dictation

Right now, every prompt you send to Claude Code in Cursor requires typing. That works fine for short commands, but natural-language prompts are faster to speak than to type.

macOS has a built-in feature called Dictation that converts your speech into typed text anywhere on your Mac. In this step, you will enable Dictation and point it at Claude Code's chat input so you can speak your prompts instead of typing them.

In this step, get ready to:

Enable macOS Dictation in System Settings.
Grant Cursor microphone access.
Test Dictation by speaking a prompt into Claude Code.

Enable macOS Dictation

Dictation is built into macOS but turned off by default. You need to flip it on in System Settings before any app can use it.

Click the Apple menu in the top-left corner of your screen.
Click System Settings.
Click Keyboard in the sidebar (scroll down if needed).
Scroll down to the Dictation section.
Toggle Dictation to On.
Click Enable in the confirmation dialog that appears.

You should see the Dictation toggle turn blue, confirming the feature is now active.

What is the Dictation shortcut?

The default shortcut to start Dictation is pressing the Fn key twice (or the Globe key twice on newer keyboards). You can change this by clicking the Shortcut pop-up menu in the same Dictation section.

When Dictation is active, a microphone icon appears near your cursor and your Mac listens for speech. It stops automatically after 30 seconds of silence.

Don't see the Dictation section?

Make sure you clicked Keyboard in the sidebar, not Input Sources. The Dictation toggle lives at the bottom of the Keyboard settings page.

Help me find the Dictation toggle

Grant Cursor microphone access

Even with Dictation enabled, each app needs explicit permission to use your microphone. Cursor needs this permission before it can receive your spoken words.

In System Settings, click Privacy & Security in the sidebar.
Click Microphone.
Find Cursor in the list and make sure its toggle is turned on.

Cursor not in the list?

If Cursor does not appear in the Microphone list yet, that is normal. The first time you try to use Dictation inside Cursor, macOS will prompt you to grant permission. Click OK when that prompt appears, then return here to confirm the toggle is on.

You should see Cursor listed with its toggle enabled.

Test Dictation in Claude Code

Both settings are configured. Time to prove the voice-to-text pipeline works end-to-end inside Cursor.

Switch to Cursor.
Open the Claude Code chat panel (if it is not already visible).
Click into the chat input field so your cursor is blinking there.

Before you try it, what do you think will happen when you press Fn twice and start speaking?

Press your Dictation shortcut (Fn twice by default).
A microphone icon appears near your cursor, indicating macOS is listening.
Speak clearly: What is the capital of France.
Press the Dictation shortcut again to stop, or wait for silence.
Your spoken words appear as typed text in the chat input field.
Press Enter (or Return) to send the message to Claude Code.

Claude Code processes your message and responds with an answer. You just spoke a prompt and got a response without typing a single word.

Dictation not working in Cursor?

If nothing happens when you press Fn twice, check that your Dictation shortcut matches what you configured in System Settings > Keyboard > Dictation.

If you see a microphone permission prompt from macOS, click OK to allow it. Then try pressing Fn twice again.

If your words are not being recognised accurately, reduce background noise and speak at a normal volume. Position yourself as you would normally sit at your Mac.

Help me troubleshoot Dictation in Cursor

Why macOS Dictation instead of Cursor's built-in voice feature?

Cursor has a native voice command, but it only works inside the chat panel and has limited reliability. macOS Dictation is more mature, works system-wide (terminal, commit messages, any text field), and requires no Cursor-specific configuration.

Your voice is now wired into Claude Code. Next up, you will set up the other direction so your Mac can read Claude's responses back to you out loud.

Set Up Voice Output with Speak Selection

You can now speak prompts directly into Claude Code. But the conversation is still one-sided because you have to read every response on screen.

macOS has a built-in feature called Speak Selection that reads any highlighted text out loud. In this step, you'll enable it so your Mac can read Claude's responses back to you.

In this step, get ready to:

Enable Speak Selection in macOS Accessibility settings.
Download a high-quality voice for natural-sounding speech.
Test voice output on Claude's response in Cursor.

Enable Speak Selection

Speak Selection is an accessibility feature that lets your Mac read any selected text out loud. Once enabled, a single keyboard shortcut turns any text on screen into speech.

Open System Settings from the Apple menu in the top-left corner of your screen.
Click Accessibility in the sidebar.
Scroll down and click Read and Speak.
Toggle on Speak selection.

The default keyboard shortcut is Option+Esc. You'll use this to trigger speech whenever you have text selected.

Want a different shortcut?

Click the info button (i) next to Speak selection to change the keyboard shortcut to something you find more comfortable.

Don't see Read and Speak?

On macOS Sequoia (15) and earlier, this section is called Spoken Content instead of Read and Speak. Look for that name under Accessibility if you're on an older version.

help me find the Speak Selection setting on my version of macOS

Choose a natural-sounding voice

The default system voice works, but downloading a higher-quality voice makes listening to Claude's responses much more pleasant. These enhanced voices sound more natural and are easier to follow for longer text.

In the same Read and Speak settings, click the System voice pop-up menu.
Click the info button (i) next to System voice to browse all available voices.
Look for voices marked with a download icon. These are higher-quality voices that sound more natural (e.g., Samantha or Zoe for English).
Click a voice name to download it, then select it as your system voice.
Adjust the Speaking rate slider to a speed that feels comfortable for you.

Which voice should I pick?

Any downloaded voice will be a big improvement over the default. Pick one that sounds pleasant to you. You can always change it later. A slightly faster speaking rate works well for listening to code explanations since you can always re-read the text on screen if you miss something.

Test it on Claude's response

All the pieces are in place. Time to hear your Mac speak for the first time.

Switch back to Cursor where Claude Code has already responded to your test prompt from Step 1.
Select Claude's response text by clicking and dragging over it. You can also press Cmd+A if the response area is focused.

Before you press the shortcut, what do you expect to happen when you trigger Speak Selection on the highlighted text?

Press Option+Esc (or your custom shortcut).

Your Mac reads the selected text aloud in the voice you chose. You should hear Claude's response spoken back to you.

Press Option+Esc again to stop the speech when you're done listening.

Not hearing anything?

Make sure your Mac's volume is turned up. Check that you actually have text selected in Cursor before pressing the shortcut.

If the shortcut does nothing, go back to System Settings > Accessibility > Read and Speak and confirm that Speak selection is still toggled on.

help me troubleshoot why Speak Selection isn't working in Cursor

Your Mac can now speak any text you select on command. Next up, you'll configure a Claude Code hook that announces when Claude finishes thinking. That way you won't have to watch the screen waiting for a response.

Make Claude Announce When It Is Done

Your voice loop is halfway there. You can speak prompts into Claude Code and hear responses read aloud.

There is still one gap. After you send a message, you have to keep watching the screen to know when Claude finishes thinking. A Notification hook fixes this by making your Mac say "Ready" out loud the moment Claude is waiting for your next input. You can look away from the screen or multitask while Claude thinks.

In this step, get ready to:

Open and configure the Claude Code settings file.
Add a Notification hook that triggers the macOS say command.
Test that your Mac speaks out loud when Claude finishes responding.

Open the Claude Code settings file

Claude Code stores its user-level settings in a JSON file at ~/.claude/settings.json. This file might not exist yet on your machine, so the first step is to check.

Press Cmd+Space to open Spotlight.
Type Terminal and press Enter to open it.
Try opening the settings file by running this command:

open ~/.claude/settings.json

✔️ A text editor opened with the file

The file already exists on your machine. You are ready to edit it in the next substep.

ⓧ I see 'does not exist' in Terminal

The file has not been created yet. Create the directory and an empty settings file by running this command:

mkdir -p ~/.claude && echo '{}' > ~/.claude/settings.json && open ~/.claude/settings.json

A text editor opens with {} inside. You are ready to edit it.

Still seeing an error?

Make sure you copied the full command including && between each part. The mkdir -p flag creates all parent folders without complaining if they already exist.

help me fix this Terminal error when creating settings.json

Add a Notification hook that speaks

Claude Code hooks let you run any shell command when certain events happen. The Notification event fires when Claude finishes responding and is waiting for your input.

Select all the text in the file (Cmd+A) and replace it with the following:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "say Ready"
          }
        ]
      }
    ]
  }
}

What does this configuration do?

hooks is the top-level key that tells Claude Code you want to run commands on certain events.
Notification is the event type. It fires when Claude Code sends a notification, which includes the moment Claude finishes responding and is waiting for your next message.
"command": "say Ready" runs the macOS say command, which speaks text out loud through your speakers.

Save the file by pressing Cmd+S.

Do I need to restart Claude Code?

No. Claude Code watches its settings files and reloads them automatically when they change. Your new hook is already active.

Worried you mistyped something?

JSON is strict about matching braces and commas. Make sure every opening { has a closing } and every opening [ has a closing ].

help me check if my settings.json is valid JSON

✔️ Awesome, I've got everything!

Great. Make sure you have saved the file before moving on.

ⓧ I'd like to double check the full code

Here is the complete ~/.claude/settings.json file:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "say Ready"
          }
        ]
      }
    ]
  }
}

Test the voice notification

Before you test, think about what you expect to happen. When you send a message to Claude Code and it finishes responding, what should you hear?

Switch back to Cursor and click into the Claude Code chat input.
Type or dictate a short message like "What is a hook" and press Enter to send.
Look away from the screen and wait.

After a few seconds, you hear your Mac say "Ready" out loud. That is the Notification hook firing the say command the moment Claude finishes its response.

Don't hear anything?

Check that your Mac's volume is turned up (press the volume-up key or check the menu bar icon).
Open Terminal and run say Ready manually. If you hear it there but not from Claude Code, open ~/.claude/settings.json and verify the JSON matches the code above exactly.
Send another message to Claude Code to trigger the hook again.

help me troubleshoot my Claude Code Notification hook

Your Mac now announces the moment Claude is done thinking. Next up, you will put all three pieces together and have a full voice conversation with Claude Code without touching your keyboard.

Have a Full Voice Conversation

Your Mac can now hear you, read text aloud, and announce when Claude finishes thinking. Each piece works on its own.

In this step, you will chain all three together into a flowing conversation loop. You speak, Claude thinks, your Mac says "Ready", you listen to the response, then you speak again. The goal is to prove the full hands-free loop works end-to-end and find your rhythm.

In this step, get ready to:

Speak a prompt to Claude Code using Dictation.
Listen to Claude's response using Speak Selection.
Complete a 3-turn voice conversation without typing your prompts.

Start a conversation with your voice

The first turn tests the voice-in side of the loop. You will dictate a prompt, send it, and wait for the "Ready" announcement without watching the screen.

Switch back to Cursor and click into the Claude Code chat input field.
Press your Dictation shortcut (Fn twice by default).
A microphone icon appears near your cursor. Speak clearly: "Explain what a Claude Code hook is in one sentence."
Press the Dictation shortcut again to stop, or wait for the silence timeout.
Press Enter to send the message to Claude Code.
Look away from the screen and wait.

After a few seconds, your Mac says "Ready" out loud. That is your signal that Claude has finished responding.

Don't hear "Ready" after sending?

Make sure your Mac's volume is turned up. Also confirm that the Notification hook is still in ~/.claude/settings.json from the previous step. Claude Code reloads the file automatically, but if the JSON has a typo the hook will not fire.

help me troubleshoot why my Claude Code Notification hook is not firing the say command

Listen to Claude's response

Now test the voice-out side. Instead of reading Claude's answer on screen, you will have your Mac read it to you.

When you hear "Ready", look at the screen.
Select Claude's response text. You can click and drag over the response, or click into the response area and press Cmd+A if it is the only content focused.
Press Option+Esc (or your custom Speak Selection shortcut).
Your Mac reads the selected text aloud in the voice you configured earlier.

You should hear a clear, natural-sounding explanation of what a Claude Code hook is. Press Option+Esc again to stop the speech if you have heard enough.

Selecting just Claude's response

If Cmd+A selects too much (your prompt plus the response), click at the start of Claude's answer and shift-click at the end instead. This keeps the readback focused on the answer only.

Continue the conversation by voice

One turn proves the pieces connect. Three turns prove you have a working conversation loop. Time to go hands-free for two more rounds.

Click into the chat input field.
Press your Dictation shortcut (Fn twice).
Speak a follow-up: "Can you give me an example of when I would use one."
Stop dictation and press Enter to send.
Look away and wait for "Ready".
When you hear it, select Claude's new response and press Option+Esc to listen.

That is turn two complete. One more to go.

Click into the input, press your Dictation shortcut, and speak a third prompt: "What happens if the hook command fails."
Stop dictation and press Enter.
Wait for "Ready", select the response, and press Option+Esc to hear it.

Before you count this as done, think about what just happened. Did you type any of your prompts, or did you speak all three?

If you spoke all three prompts, heard "Ready" each time, and listened to each response, you have a confirmed end-to-end voice conversation loop with Claude Code.

Dictation inserting wrong words?

Speak slightly slower and enunciate technical terms. Dictation sometimes misinterprets jargon like "hook" or "JSON". You can always correct a word by selecting it and re-dictating just that word before pressing Enter.

help me get better dictation accuracy for technical terms in Cursor

You just had a full spoken conversation with Claude Code without typing a single prompt. Next up, you will customize the announcement voice, phrase, and sound effects to make the workflow feel like yours.

Customize Your Voice Workflow

You just proved the full voice loop works. You can speak a prompt, hear "Ready" when Claude finishes, and listen to the response out loud.

The default "Ready" announcement is functional but generic. Customizing the voice, the phrase, and adding a sound effect makes the workflow feel personal and reduces friction for daily use.

In this step, get ready to:

Customize the announcement phrase and voice in your Notification hook.
Add a system sound effect before the spoken announcement.
Fine-tune your Speak Selection speaking rate for faster readback.

Customize the announcement phrase

The macOS say command accepts a -v flag that lets you pick any installed voice by name. Combining a custom voice with a personalized phrase makes the notification unmistakably yours.

See which voices are available on your Mac by running this command in Terminal:

say -v ?

You will see a long list of voice names, languages, and sample phrases scroll by in the terminal.

Pick a voice you like from the list (for example, Samantha is a natural-sounding English voice).
Open your settings file by running:

open ~/.claude/settings.json

In the file, find this line:

"command": "say Ready"

Replace it with this line, which uses the -v flag and a new phrase:

"command": "say -v Samantha Claude is done"

Save the file (Cmd+S).
Switch back to Cursor and send Claude Code a short message (type or dictate something like "Say hello").
Wait for Claude to finish responding. You should hear "Claude is done" spoken in Samantha's voice.

Don't hear the new voice?

Make sure you saved the file. Claude Code watches settings files and reloads them automatically, but only after a save.

Double-check that the voice name matches exactly what appeared in the say -v ? output. Voice names are case-sensitive.

Why isn't my custom say voice working in the Claude Code hook?

Add a sound effect before the announcement

You can chain multiple commands together so a system sound plays right before the spoken phrase. The afplay command plays audio files, and && runs the next command only after the first finishes.

In your settings file, find this line:

"command": "say -v Samantha Claude is done"

Replace it with this line, which plays the Glass sound before speaking:

"command": "afplay /System/Library/Sounds/Glass.aiff && say -v Samantha Your turn"

What does this command do?

afplay /System/Library/Sounds/Glass.aiff plays the Glass chime built into macOS.
&& waits for the sound to finish, then runs the next command.
say -v Samantha Your turn speaks "Your turn" in the Samantha voice.

Other sounds you can try include Hero.aiff, Ping.aiff, and Pop.aiff. They all live in /System/Library/Sounds/.

Save the file (Cmd+S).

Before you test this, what do you expect to hear when Claude finishes responding? Think about the order of sounds.

Switch back to Cursor and send Claude Code another short message.
Wait for Claude to finish. You should hear the Glass chime followed by "Your turn" in Samantha's voice.

Only hearing the chime but no speech?

Check that you have && between the two commands (not a single &). A single & runs both commands simultaneously, which can cause the speech to be cut off.

Also verify there are no extra quotes or line breaks inside the command value. The entire string should be on one line.

Help me fix my chained afplay and say command in my Claude Code hook.

✔️ Awesome, I've got everything!

Great. Double check you have saved your settings.json file.

ⓧ I'd like to double check the full code

Your ~/.claude/settings.json should look exactly like this:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff && say -v Samantha Your turn"
          }
        ]
      }
    ]
  }
}

Fine-tune your Speak Selection voice

The speaking rate for Speak Selection controls how fast your Mac reads Claude's responses. A faster rate means less waiting between turns in your conversation.

Open System Settings (Apple menu > System Settings).
Click Accessibility in the sidebar.
Click Read and Speak.
Click the info button (i) next to System voice to open voice options.
Drag the Speaking Rate slider to the right to increase the speed.
Click Play Sample to preview the new rate.
Adjust until it feels natural but noticeably faster than the default.

Switch back to Cursor and select some of Claude's response text from your earlier conversation.
Press Option+Esc to hear it read at your new speed.

You should hear the selected text read noticeably faster than before, matching the rate you just set.

Find your rhythm

A speed that is comfortable for listening to a full paragraph is usually about 1.5x the default. Too fast and you will miss details. Experiment over a few conversations to find the sweet spot.

Secret mission

Make Claude Read Its Own Response Automatically

Right now you have to manually select Claude's response and press Option+Esc to hear it. What if Claude could announce itself automatically the moment it finishes, with zero manual selection required? In this secret mission, you will add a Stop hook that makes your Mac speak the moment Claude finishes responding.

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally using macOS system settings and a single JSON file, so there are no ongoing costs.

Resources you used:

macOS Dictation (System Settings > Keyboard).
macOS Speak Selection (System Settings > Accessibility > Read and Speak).
Claude Code hooks in ~/.claude/settings.json.
Cursor microphone permission (System Settings > Privacy and Security > Microphone).

Keep everything running

No action needed. Choose this if you plan to keep using voice conversations with Claude Code.

Dictation stays enabled system-wide and works in any app.
Speak Selection stays available for reading any selected text aloud.
Your Claude Code hooks continue to fire every time Claude finishes responding.
Cursor retains microphone access for future Dictation use.

Pause - I'll come back to this later

Disable the voice features temporarily without removing your configuration. You can re-enable everything in a few clicks later.

Open System Settings > Keyboard and toggle Dictation off.
Open System Settings > Accessibility > Read and Speak and toggle Speak selection off.
Your ~/.claude/settings.json file stays in place. Claude Code ignores hooks when it is not running, so no action is needed there.

Delete - I don't want to use this again

Remove all project resources and revert your system to its previous state.

Open System Settings > Keyboard and toggle Dictation off.
Open System Settings > Accessibility > Read and Speak and toggle Speak selection off.
Open System Settings > Privacy and Security > Microphone and toggle Cursor off to revoke microphone access.
Remove your Claude Code hooks by running this command in Terminal:

echo '{}' > ~/.claude/settings.json

This resets the file to an empty JSON object, removing all hooks you configured.

Why not delete the file entirely?

Claude Code expects ~/.claude/settings.json to exist for user-level settings. Resetting it to {} is cleaner than deleting it, because Claude Code will recreate it anyway.

Nice Work!

You just built a hands-free voice conversation loop with Claude Code in Cursor. You can now speak your prompts, hear when Claude is ready, and listen to responses read aloud.

You've learned how to:

Set up macOS Dictation to speak prompts directly into Claude Code's chat panel in Cursor.
Configure a Claude Code Notification hook that runs a shell command the moment Claude is ready for your next message.
Complete a multi-turn voice conversation with Claude Code without typing your prompts, using Dictation, Speak Selection, and a custom announcement together.
Secret Mission: Configure a Stop hook to make Claude automatically speak its response when it finishes, removing the manual select-and-listen step entirely.

Ready to quiz yourself?