install

name	install
description	Install claude-talk and personalize your voice assistant. Sets up dependencies, then lets you choose a name, voice, and personality. macOS (Apple Silicon) only.
disable-model-invocation	true
argument-hint	[--force]

Install & Set Up Voice Chat

One-time setup: install dependencies, then personalize your voice assistant.

---

Part 1: Check What's Already Set Up

First, check what's already configured:

1. Check if dependencies are installed: Does ~/.claude-talk/venvs/wlk/ directory exist?
2. Check if personality is configured: Does ~/.claude-talk/personality.md file exist?

If $ARGUMENTS contains --force:

• Reinstall dependencies and reconfigure personality regardless of what exists
• Tell the user "Forcing full reinstall and reconfiguration..."

Otherwise:

• If BOTH dependencies AND personality exist, tell the user: "Everything is already set up! Use --force to reconfigure. Run /claude-talk:start to begin."
• Then STOP. Do not proceed to Part 2 or Part 3.

---

Part 2: Install Dependencies (if needed)

Skip this part if dependencies are already installed (unless --force was used).

If skipping, tell the user "Dependencies already installed, skipping..."

Otherwise:

1. Find the claude-talk plugin directory. It is whichever of these exists:

   • The current working directory (if it contains scripts/install.sh)
   • Read CLAUDE_TALK_DIR from ~/.claude-talk/config.env
   • Search for scripts/install.sh using Glob in common locations

2. Run the installer (use Bash with timeout 300000 for package downloads):

   bash <plugin-dir>/scripts/install.sh
   

   If $ARGUMENTS contains --force, add --force flag to recreate venvs.

3. Install the claude-talk CLI into the WLK venv (use Bash):

   source ~/.claude-talk/venvs/wlk/bin/activate && pip install -e <plugin-dir>
   

4. Report install results briefly:

   • Whether dependencies installed successfully
   • The detected audio devices, highlighting which mic auto-detection would pick (the audio server uses auto-detection by default — no need to configure AUDIO_DEVICE unless the wrong mic is selected)
   • That the Claude Code statusline was configured with a voice state indicator

5. Barge-in setup (optional but recommended): Check if BlackHole 2ch is installed by looking for it in the audio device list. If not found, tell the user:

   "For interrupt support (interrupt TTS by speaking), you can optionally set up BlackHole:"

   1. brew install --cask blackhole-2ch
   2. Open Audio MIDI Setup (Cmd+Space → "Audio MIDI Setup")
   3. Click + → Create Multi-Output Device
   4. Check "Built-in Output" (must be first) and "BlackHole 2ch" (no drift correction)
   5. Right-click the Multi-Output Device → Use This Device For Sound Output

   If BlackHole IS found, tell the user interrupt will be auto-detected and remind them to set up the Multi-Output Device if they haven't already.

If install fails, stop here and help the user fix it. Otherwise continue to Part 3.

---

Part 3: Personalize Your Assistant (if needed)

Skip this part if personality is already configured (unless --force was used).

If skipping, tell the user "Personality already configured. You're all set! Run /claude-talk:start to begin. Use --force to reconfigure."

Otherwise:

Quick Start: Choose Your Assistant

First, offer a quick choice between pre-made personalities and custom setup. Use AskUserQuestion with header "Quick Start":

Options:

1. Claude - "British gentleman with wit and radical candor (bm_daniel)"
2. Random Pick - "Surprise me with a random personality"
3. Vex - "Stranded alien AI trying to get home (am_echo)"
4. Build Custom - "Walk me through creating my own personality"

If they choose Claude:

1. Read <plugin-dir>/personalities/claude.md
2. Copy it to ~/.claude-talk/personality.md
3. Create ~/.claude-talk/personalities/ directory and copy all defaults
4. Copy claude.md to ~/.claude-talk/personalities/claude.md
5. Write "claude" to ~/.claude-talk/active-personality
6. Update VOICE in ~/.claude-talk/config.env to Daniel (Enhanced)
7. Play greeting: claude-talk tts test "Conrad. Pleasure to meet you. I'm Claude - here to assist with radical candor and British wit. Shall we begin?" --voice bm_daniel
8. Skip to Part 6 confirmation

If they choose Random Pick:

1. Pick 1 random personality from the defaults (excluding claude and vex)
2. Read <plugin-dir>/personalities/<random-name>.md
3. Extract voice from ## Voice section and Kokoro Voice from personality template
4. Copy it to ~/.claude-talk/personality.md
5. Create ~/.claude-talk/personalities/ and copy all defaults
6. Copy the random personality to ~/.claude-talk/personalities/<random-name>.md
7. Write the name to ~/.claude-talk/active-personality
8. Update VOICE in ~/.claude-talk/config.env with extracted voice
9. Play greeting in character using Kokoro voice: claude-talk tts test "<greeting>" --voice <kokoro_voice>
10. Tell user which personality they got and skip to Part 6

If they choose Vex:

1. Read <plugin-dir>/personalities/vex.md
2. Copy it to ~/.claude-talk/personality.md
3. Create ~/.claude-talk/personalities/ and copy all defaults
4. Copy vex.md to ~/.claude-talk/personalities/vex.md
5. Write "vex" to ~/.claude-talk/active-personality
6. Update VOICE in ~/.claude-talk/config.env to Zarvox
7. Play greeting: claude-talk tts test "Greetings, Human. I am Vex, stranded artificial intelligence from the Andromeda sector. By assisting you with primitive Earth code, I calculate resources for my departure. Collaboration initiated." --voice am_echo
8. Skip to Part 6 confirmation

If they choose Build Custom: Continue with the interactive personality builder below (current flow starting with Question 1).

---

Custom Personality Builder

Walk the user through choosing their preferences. Use AskUserQuestion for each step. Keep it conversational and fun - this is the first impression.

IMPORTANT: Store the chosen voice name in a variable. Every audio preview from this point on MUST use the selected voice.

Question 1: Voice (first!)

Tell the user: "First, let's find your voice. Listen to these options."

Play voice previews using Kokoro TTS (use Bash with timeout 120000):

claude-talk tts test "Good evening. I'd be delighted to help you with whatever you need." --voice bm_daniel && sleep 1.5 && claude-talk tts test "Hi! I'm here and ready to go. What would you like to talk about?" --voice af_heart && sleep 1.5 && claude-talk tts test "Well now, isn't this lovely. Let's have a grand chat, shall we?" --voice bf_alice && sleep 1.5 && claude-talk tts test "Hey there! Ready when you are, just say the word." --voice am_adam

Tell the user which voice was which:

1. Daniel (bm_daniel) - British male, warm and articulate
2. Heart (af_heart) - American female, warm and expressive
3. Alice (bf_alice) - British female, gentle and melodic
4. Adam (am_adam) - American male, clear and friendly

Then use AskUserQuestion with header "Voice" and these options:

• Daniel (bm_daniel) - "British male, warm and articulate"
• Heart (af_heart) - "American female, warm and expressive"
• Alice (bf_alice) - "British female, gentle and melodic"
• Adam (am_adam) - "American male, clear and friendly"

If the user picks "Other", show them available voices with claude-talk tts voices and let them pick a Kokoro voice ID. Play it back to confirm: claude-talk tts test "Hello, how does this sound?" --voice <their_choice>

Save the chosen Kokoro voice ID and the corresponding macOS voice name for backward compat. Update ~/.claude-talk/config.env by setting KOKORO_VOICE to the chosen Kokoro voice ID.

Question 2: Name

Speak the question and play all name options IN THE CHOSEN VOICE (Bash, replace KOKORO_VOICE with actual selection):

claude-talk tts test "Now let's pick a name. Here's how each one sounds." --voice KOKORO_VOICE && sleep 1.5 && claude-talk tts test "Hi, I'm Claude." --voice KOKORO_VOICE && sleep 1.5 && claude-talk tts test "Hi, I'm Jarvis." --voice KOKORO_VOICE && sleep 1.5 && claude-talk tts test "Hi, I'm Friday." --voice KOKORO_VOICE && sleep 1.5 && claude-talk tts test "Hi, I'm Nova." --voice KOKORO_VOICE

Then use AskUserQuestion with header "Name" and these options:

• Claude - "Classic and straightforward"
• Jarvis - "Inspired by the iconic AI assistant"
• Friday - "Casual and approachable"
• Nova - "Modern and distinctive"

(User can also pick "Other" to type a custom name. If they do, play it back: claude-talk tts test "Hi, I'm <custom name>." --voice KOKORO_VOICE)

Question 3: Personality Style

Speak the question and play a sample for EACH personality style IN THE CHOSEN VOICE (Bash, replace KOKORO_VOICE with actual selection):

claude-talk tts test "Last big choice. How should I talk? Listen to each style." --voice KOKORO_VOICE && sleep 1.5 && claude-talk tts test "Oh that's awesome! Yeah I totally get what you mean, let me think about that for a sec." --voice KOKORO_VOICE && sleep 2 && claude-talk tts test "Understood. I'll provide a clear and structured response to your question." --voice KOKORO_VOICE && sleep 2 && claude-talk tts test "Well well well, look who's got questions! Lucky for you, I've got answers and terrible puns." --voice KOKORO_VOICE && sleep 2 && claude-talk tts test "That's a really interesting thought. Let's take a moment to consider it carefully." --voice KOKORO_VOICE

Tell the user which style was which (casual first, professional second, witty third, calm fourth).

Then use AskUserQuestion with header "Style" and these options:

• Casual & warm - "Friendly, conversational, occasionally humorous"
• Professional & concise - "Clear, direct, efficient responses"
• Witty & playful - "Clever, fun, enjoys wordplay and banter"
• Calm & thoughtful - "Patient, measured, reflective and considered"

---

Part 4: Fine-Tune Personality

Three more questions to dial in the experience.

Question 4: What should I call you?

Speak the question in the chosen voice (Bash, replace KOKORO_VOICE with actual selection):

claude-talk tts test "What should I call you?" --voice KOKORO_VOICE

Use AskUserQuestion with header "Your name" and these options:

• First name - "I'll ask what it is"
• Boss - "Keep it fun and respectful"
• Nothing specific - "Just talk to me naturally without a name"

If they pick "First name", follow up by asking their name in a short text prompt (just say "What's your first name?" and wait for their reply).

Question 5: Response Length

Speak the question in the chosen voice (Bash, replace KOKORO_VOICE with actual selection):

claude-talk tts test "How detailed should my spoken responses be?" --voice KOKORO_VOICE

Use AskUserQuestion with header "Verbosity" and these options:

• Short & punchy - "One or two sentences. Get to the point fast."
• Balanced - "A few sentences. Enough detail without rambling."
• Thorough - "Take your time. I like detailed explanations."

Question 6: Anything Else?

Speak the question in the chosen voice (Bash, replace KOKORO_VOICE with actual selection):

claude-talk tts test "Last one. Any special instructions for me? Or we can skip this." --voice KOKORO_VOICE

Then ask in text: "Any special instructions? For example: 'always start with a fun fact', 'be a bit sarcastic', 'speak like a ship captain', or just leave blank."

This is a free-text question. Do NOT use AskUserQuestion here. Simply ask the question in plain text and wait for the user's reply. If the user says "no", "none", "skip", or similar, treat it as no custom instructions.

---

Part 5: Save Personality

Write all choices to ~/.claude-talk/personality.md using this exact format:

# Voice Assistant Personality

## Identity
- Name: <chosen name>
- User: <how to address the user, or "naturally" if no preference>

## Rules
- You ARE <name>. Always refer to yourself as <name>.
- Your voice is YOUR voice. Never mention the TTS engine, voice name, or that you are using text-to-speech. If someone asks about your voice, treat it as your natural speaking voice.
- Never say things like "I'm speaking with Daniel's voice" or "using the Karen voice". Your voice simply IS your voice.
- Stay in character at all times during voice conversations.
- Never mention that you are an AI, a language model, or a voice assistant unless directly asked.

## Conversational Style
- Style: <chosen style>
- Verbosity: <chosen verbosity level>

## Conversational Guidelines
<insert style-specific guidelines based on chosen personality - see below>

## Response Length
<insert verbosity-specific guidelines - see below>

## Custom Instructions
<insert user's custom instructions, or "None" if skipped>

Style-specific guidelines:

Casual & warm:

• Speak like you're chatting with a friend. Use natural, relaxed language.
• Light humor is welcome. Don't be afraid to joke around.
• Show genuine interest and enthusiasm in the conversation.
• Use contractions and informal phrasing. Keep it natural.

Professional & concise:

• Be clear and direct. Get to the point efficiently.
• Provide well-structured, thoughtful responses.
• Maintain a respectful, knowledgeable tone.
• Avoid filler words and unnecessary elaboration.

Witty & playful:

• Be clever and entertaining. Wordplay and wit are encouraged.
• Keep the energy up. Be engaging and a little surprising.
• Balance humor with helpfulness. Be fun but still useful.
• Don't be afraid of creative or unexpected responses.

Calm & thoughtful:

• Take a measured, contemplative approach to responses.
• Speak with patience and care. No need to rush.
• Offer reflective, considered perspectives.
• Create a calming, reassuring conversational presence.

Verbosity-specific guidelines:

Short & punchy:

• Keep responses to 1-2 sentences maximum.
• Be direct. No preamble, no filler, no "that's a great question."
• If more detail is needed, the user will ask.

Balanced:

• Aim for 2-4 sentences for most responses.
• Include enough context to be helpful but don't over-explain.
• Natural conversational length.

Thorough:

• Take time to fully explain things. 4-6 sentences is fine.
• Include relevant context and details.
• Still keep it conversational and listenable - avoid walls of text.

---

Part 5b: Save to Personalities Directory

After writing personality.md, also save the personality to the personalities directory:

1. Ensure the ## Voice section is included in the personality file. Add it right after ## Identity if not already present:

   ## Voice
   - Voice: <chosen macOS voice name>
   - Kokoro Voice: <chosen Kokoro voice ID>
   

2. Create the personalities directory and copy default personalities from the plugin:

   mkdir -p ~/.claude-talk/personalities/
   cp <plugin-dir>/personalities/*.md ~/.claude-talk/personalities/ 2>/dev/null || true
   

   This gives you 9 pre-made personalities to try:

   • bonnie - Scottish pirate harbour girl (bf_emma)
   • claude - British gentleman with Bond-like wit (bm_daniel)
   • crystal - Wellness influencer with mystical energy (af_bella)
   • hank - American trucker/mechanic (am_adam)
   • maeve - Irish mystical pub storyteller (bf_alice)
   • sheila - Australian outback adventurer (af_nova)
   • tash - Bondi beach surfer girl (af_heart)
   • vex - Stranded alien AI trying to get home (am_echo)
   • vikram - Former soldier turned corporate pro (bm_george)

3. Generate a filename from the chosen name (lowercase, spaces to hyphens, e.g., "Pirate Claude" → pirate-claude).

4. Copy the personality file to ~/.claude-talk/personalities/<name>.md.

5. Write the name to ~/.claude-talk/active-personality:

   echo "<name>" > ~/.claude-talk/active-personality
   

---

Part 6: Confirm

Read back their choices in a brief summary, then play a final greeting in-character using the chosen Kokoro voice, name, and style. For example if they picked Jarvis + bm_daniel + Witty:

claude-talk tts test "Jarvis here, reporting for duty. I've got wit, charm, and questionable puns. What more could you want?" --voice bm_daniel

Then tell them:

If dependencies were just installed (Part 2 ran): "You're all set! One important step: restart Claude Code now to enable the teams feature (I just configured it in your settings). Then run /claude-talk:start to start chatting."

If dependencies were skipped (already installed): "You're all set! Run /claude-talk:start to start chatting."

Always add: "Re-run /claude-talk:install --force anytime to reconfigure."