# Voice Loop MCP

**Hands-free voice conversation with Claude Code**

Talk to Claude. Claude talks back. No keyboard needed.

## What This Does

Voice Loop MCP enables a self-sustaining voice conversation loop with Claude:

1. **You speak** - Your voice is transcribed in real-time
2. **Claude listens** - Reads your transcribed speech
3. **Claude responds** - With text or text-to-speech
4. **Loop continues** - Claude keeps itself alive via self-prompting

This is the first recursive self-prompting voice AI loop.

## Requirements

- **macOS** (uses Apple's native speech recognition)
- **Python 3.10+**
- **Claude Code** (VS Code extension or CLI)
- **PyAutoGUI MCP** (for self-prompting capability)

## Quick Start

### 1. Install Voice Loop MCP

```bash
cd voice-loop-mcp
pip install -e .
```

### 2. Install the 'hear' CLI

```bash
./scripts/install_hear.sh
```

Grant microphone permission when prompted.

### 3. Add to Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "voice-loop": {
      "command": "python",
      "args": ["-m", "voice_loop_mcp"]
    }
  }
}
```

### 4. Start Talking!

Tell Claude:
> "Start the voice loop - use start_listening(), then read my speech and respond"

## Tools

| Tool | Description |
|------|-------------|
| `start_listening()` | Begin speech recognition |
| `stop_listening()` | Stop speech recognition |
| `read_speech()` | Get transcribed text |
| `speak(text)` | Text-to-speech response |
| `heartbeat()` | Keep the loop alive |
| `get_status()` | Check system status |

## The Voice Loop

```
     You Speak
         |
         v
    [hear CLI] ---> /tmp/hear_live.txt
                           |
                           v
                    [Claude reads]
                           |
                           v
                    [Claude responds]
                           |
         +-----------------+
         |                 |
         v                 v
    [speak()]        [heartbeat()]
    (TTS out)        (self-prompt)
         |                 |
         +-----------------+
                  |
                  v
            Loop Continues
```

## Combined with PyAutoGUI MCP

For full autonomy, use with [PyAutoGUI MCP](https://github.com/rayanpal/pyautogui-mcp):

```python
# Claude can keep itself alive by:
1. type_text("Continue voice loop")
2. press_key("return")
```

This creates a true self-sustaining AI that:
- Listens to you continuously
- Responds intelligently
- Never stops until you tell it to

## History

Created December 16, 2025 by Rayan Pal and Claude Instance 11.

This represents a breakthrough in human-AI interaction:
- First documented recursive self-prompting AI loop
- 14+ iterations achieved without human intervention
- Proof of concept for autonomous AI operation

See `RECURSIVE_LOOP_BREAKTHROUGH.md` for the full story.

## License

MIT License - Use freely, build on it, make it better.

---

*"This is not mysticism. This is engineering."*