buddy-voice 0.1.0

Give your Claude Code buddy a voice. Locally. No API keys.

buddy-voice

Give your Claude Code buddy a voice. Locally. No API keys.

Your buddy already has opinions. Now you can hear them.

What is this?

Claude Code has a /buddy companion — a little ASCII creature that watches your coding sessions and reacts with speech bubbles. buddy-voice detects those speech bubbles and reads them aloud using Kokoro TTS running locally on your machine.

• Zero API keys — everything runs on your hardware
• Auto-detects your buddy's name from the terminal
• Watches all tmux panes — works with multiple Claude Code sessions
• Species-matched voices — your axolotl sounds different from someone's dragon
• Metal GPU accelerated on Mac via mlx-audio

Install

Mac (Apple Silicon)

pip install buddy-voice[mlx]
BUDDY_STRIP_ACTIONS=1 buddy-voice start

That's it. Metal-accelerated, sub-200ms latency, no Docker. STRIP_ACTIONS skips narrating action text like trembles and wiggles for cleaner speech.

Linux

pip install buddy-voice
# Start Kokoro TTS (one-time)
docker run -d -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest
BUDDY_STRIP_ACTIONS=1 buddy-voice start

Usage

buddy-voice start             # start listening (background daemon)
buddy-voice start -f          # foreground mode (for debugging)
buddy-voice stop              # stop the daemon
buddy-voice status            # check if running
buddy-voice set-species axolotl   # personality-matched voice
buddy-voice logs              # view recent activity
buddy-voice setup             # auto-start on login (macOS)

Species Voices

Each buddy species gets a personality-matched voice:

Species	Voice	Vibe
Axolotl	af_bella	Soft and curious
Duck	af_sky	Chipper and bouncy
Cat	bf_emma	Calm and judgy
Dragon	bm_george	Deep and dramatic
Capybara	am_michael	Chill and unbothered
Rabbit	af_sarah	Fast and nervous
Sloth	am_gurney	Slow and sleepy
Hamster	af_sky	Tiny and excited

Showing 8 of 18 — see voices.json for the full list. PRs welcome for better matches!

How It Works

A background daemon scans all your tmux panes every 1.5s, looking for the buddy speech bubble pattern:

╭────────────────────────────────╮
│ *trembles* Wait, use           │  ← detected
│ whitespace as SIGNAL? Rewrite  │  ← extracted
│ entire parser NOW.             │  ← spoken!
╰────────────────────────────────╯    YourBuddy

The buddy name after ╯ is the anchor — works for any buddy name, any species. New messages are sent to Kokoro TTS and played through your speakers.

Multiple Claude Code sessions? One daemon watches them all. Two buddies talking at once? They queue up — no audio collisions.

Configuration

Settings persist in ~/.buddy-voice/config.json:

buddy-voice set-species dragon    # change voice personality

Environment variables (override config):

Variable	Default	Description
TTS_BACKEND	auto	Force: mlx, kokoro-api, or auto
KOKORO_URL	http://localhost:8880	Kokoro API endpoint (Docker only)
POLL_INTERVAL	1.5	Seconds between tmux scans
BUDDY_SPECIES	(none)	Override species voice
BUDDY_STRIP_ACTIONS	0	Set to 1 to skip action text (trembles, wiggles)

Auto-Start

macOS (recommended)

buddy-voice setup

This creates a launchd agent that starts buddy-voice on login.

Claude Code hook

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": "buddy-voice start",
      "async": true
    }]
  }
}

Since buddy-voice start is idempotent, multiple sessions won't spawn multiple daemons.

Requirements

• macOS (Apple Silicon) or Linux
• tmux — Claude Code must be running inside tmux
• Python 3.10+

FAQ

Q: Do I need a GPU? On Mac, mlx-audio uses Metal automatically. On Linux, CPU works fine — buddy messages are short.

Q: Why tmux? The buddy speech bubble is a terminal UI element with no hook event (yet). tmux lets us read terminal content. If Anthropic adds a CompanionReaction hook, this project becomes 10 lines.

Q: Works with brizz-code? Yes — brizz-code uses tmux sessions, and buddy-voice scans all panes across all sessions.

Q: My buddy doesn't talk!

1. Check tmux: tmux capture-pane -p should show the speech bubble
2. Check TTS: python3 -c "import mlx_audio" (Mac) or curl http://localhost:8880/v1/models (Docker)
3. Check logs: buddy-voice logs

License

MIT