Metadata-Version: 2.4
Name: buddy-voice
Version: 0.1.1
Summary: Give your Claude Code buddy a voice. Locally. No API keys.
Project-URL: Homepage, https://github.com/MoJony/buddy-voice
Project-URL: Repository, https://github.com/MoJony/buddy-voice
Author: MoJony
License-Expression: MIT
License-File: LICENSE
Keywords: buddy,claude-code,companion,kokoro,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Provides-Extra: mlx
Requires-Dist: mlx-audio[tts]; extra == 'mlx'
Requires-Dist: soundfile; extra == 'mlx'
Description-Content-Type: text/markdown

# 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](https://huggingface.co/hexgrad/Kokoro-82M) 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](https://github.com/Blaizzy/mlx-audio)

## Install

### Mac (Apple Silicon)

```bash
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

```bash
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

```bash
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](src/buddy_voice/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`:

```bash
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)

```bash
buddy-voice setup
```

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

### Claude Code hook

Add to `~/.claude/settings.json`:

```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
