agentvibes 5.3.0 → 5.4.0

package/.claude/docs/TERMUX_SETUP.md

@@ -1,408 +1,408 @@
-# Termux SSH TTS Provider Setup Guide
-
-## Overview
-
-The `termux-ssh` provider allows AgentVibes to send TTS audio output to your Android device when you're connected from Termux via SSH. Instead of playing audio locally on your server/desktop, text is sent to your phone via SSH and spoken using Android's native TTS engine (`termux-tts-speak`).
-
-**Use Case:** You're working on a remote server (VPS, cloud instance, home server) and want to hear AgentVibes TTS on your Android phone instead of the server's speakers.
-
-### Why This Provider?
-
-- **Solves PulseAudio issues**: PulseAudio tunneling doesn't work reliably on Android/Termux
-- **Uses native Android TTS**: High-quality voices from Google TTS or other installed engines
-- **Near-instant**: Only sends text, not audio files
-- **Works from anywhere**: With Tailscale, access your Android from any network
-- **No configuration overhead**: Works with standard SSH setup
-
-## Prerequisites
-
-> **💡 Tip:** Install Tailscale first (see [Advanced Configuration](#using-tailscale-for-internet-wide-access-recommended)) for the best experience. It allows you to access your Android device from anywhere, not just your local WiFi.
-
-### On Android Device (Termux)
-
-1. **Install Termux** from F-Droid (NOT Google Play - it's outdated)
-   ```bash
-   # Download from: https://f-droid.org/en/packages/com.termux/
-   ```
-
-2. **Install required packages**:
-   ```bash
-   pkg update
-   pkg install termux-api openssh
-   ```
-
-3. **Install Termux:API app** from F-Droid:
-   ```bash
-   # Download from: https://f-droid.org/en/packages/com.termux.api/
-   ```
-
-4. **Start SSH server**:
-   ```bash
-   # Generate SSH keys (first time only)
-   ssh-keygen -t rsa -b 4096
-
-   # Start SSH daemon
-   sshd
-
-   # Find your SSH port (usually 8022)
-   cat $PREFIX/var/run/sshd.pid
-   ```
-
-5. **Get your device IP address**:
-
-   **Option A: Tailscale IP (Recommended)**
-   ```bash
-   # After installing Tailscale (see Advanced Configuration)
-   tailscale ip -4
-   # Example: 100.100.100.100
-   ```
-
-   **Option B: Local WiFi IP (Same Network Only)**
-   ```bash
-   # Only works when both devices are on the same WiFi
-   ifconfig wlan0 | grep "inet addr"
-   # Example: 192.168.1.100
-   ```
-
-   > ⚠️ **Local WiFi IPs only work on the same network.** Use Tailscale for reliable access from anywhere.
-
-### On Server/Desktop
-
-1. **Copy SSH public key to Android**:
-   ```bash
-   # On your desktop/server
-   ssh-copy-id -p 8022 u0_a###@<android-ip>
-
-   # Replace:
-   # - u0_a### with your Termux username (run 'whoami' in Termux)
-   # - <android-ip> with your Android device IP
-   ```
-
-2. **Configure SSH host alias** in `~/.ssh/config`:
-   ```ssh-config
-   Host android
-       HostName <your-android-ip>
-       User <your-termux-username>
-       Port 8022
-       IdentityFile ~/.ssh/id_rsa
-       ServerAliveInterval 60
-       ServerAliveCountMax 3
-   ```
-
-   **Example**:
-   ```ssh-config
-   Host android
-       HostName 100.100.100.100    # Tailscale IP
-       User u0_a123                # From 'whoami' in Termux
-       Port 8022
-       IdentityFile ~/.ssh/id_ed25519
-       ServerAliveInterval 60
-   ```
-
-3. **Test SSH connection**:
-   ```bash
-   ssh android "echo 'Connection successful!'"
-   ```
-
-## AgentVibes Configuration
-
-### 1. Set SSH Host Alias
-
-Choose ONE of these methods:
-
-**Option A: Environment Variable** (Temporary)
-```bash
-export TERMUX_SSH_HOST="android"
-```
-
-**Option B: Global Config File** (Recommended)
-```bash
-echo "android" > ~/.claude/termux-ssh-host.txt
-```
-
-**Option C: Project-Specific**
-```bash
-echo "android" > /path/to/project/.claude/termux-ssh-host.txt
-```
-
-### 2. Switch to termux-ssh Provider
-
-```bash
-# Using slash command (in Claude Code)
-/agent-vibes:provider switch termux-ssh
-
-# Or manually
-echo "termux-ssh" > ~/.claude/tts-provider.txt
-```
-
-### 3. Verify Setup
-
-```bash
-# List available providers (should include termux-ssh)
-/agent-vibes:provider list
-
-# Check active provider
-/agent-vibes:provider get
-
-# Test TTS
-.claude/hooks/play-tts.sh "Testing Android TTS via SSH"
-```
-
-## Usage
-
-Once configured, AgentVibes will automatically route TTS to your Android device:
-
-```bash
-# TTS plays on your Android phone, not the server
-.claude/hooks/play-tts.sh "This will play on my Android device"
-```
-
-## Troubleshooting
-
-### "Cannot connect to SSH host 'android'"
-
-**Possible causes**:
-1. SSH server not running on Android: `sshd` in Termux
-2. Wrong IP/hostname in ~/.ssh/config
-3. Firewall blocking port 8022
-4. Android device not on same network (or no VPN connection)
-
-**Debug**:
-```bash
-# Test SSH connection manually
-ssh android "echo ok"
-
-# Check SSH config
-cat ~/.ssh/config | grep -A5 "Host android"
-
-# Verify sshd is running on Android
-ssh android "ps aux | grep sshd"
-```
-
-### "termux-tts-speak: command not found"
-
-**Solution**:
-```bash
-# On Android (Termux)
-pkg install termux-api
-
-# Verify installation
-which termux-tts-speak
-```
-
-### "Provider 'termux-ssh' not found"
-
-**Solution**:
-```bash
-# Verify provider file exists
-ls -la .claude/hooks/play-tts-termux-ssh.sh
-
-# Check if executable
-chmod +x .claude/hooks/play-tts-termux-ssh.sh
-
-# List providers to confirm
-/agent-vibes:provider list
-```
-
-### Audio plays but very slow/delayed
-
-This is normal for the first invocation. Subsequent calls should be instant.
-
-**Optimization**:
-```bash
-# Add ControlMaster to ~/.ssh/config for connection pooling
-Host android
-    ControlMaster auto
-    ControlPath ~/.ssh/sockets/%r@%h-%p
-    ControlPersist 10m
-```
-
-## Advanced Configuration
-
-### Using Tailscale for Internet-Wide Access (Recommended)
-
-#### Why Use Tailscale?
-
-**The Problem:**
-- Your Android device and server are on different networks (home WiFi, mobile data, office)
-- SSH requires both devices on the same local network OR a public IP with port forwarding
-- Port forwarding is complex, insecure, and often blocked by carriers/ISPs
-- Public WiFi networks block SSH connections
-
-**The Solution: Tailscale**
-
-Tailscale creates a secure, private VPN network between your devices that works from anywhere:
-- ✅ Access your Android from any network (home, office, coffee shop, mobile data)
-- ✅ No port forwarding or firewall configuration needed
-- ✅ Encrypted point-to-point connections
-- ✅ Works behind NAT, firewalls, and on mobile data
-- ✅ Free for personal use (up to 100 devices)
-- ✅ Each device gets a stable private IP (100.x.x.x)
-
-#### Step 1: Install Tailscale on Android
-
-1. **Download Tailscale from Play Store:**
-   - Search for "Tailscale" in Google Play Store
-   - Install the official Tailscale app
-   - OR download APK from: https://tailscale.com/download/android
-
-2. **Connect to Tailscale:**
-   - Open Tailscale app
-   - Tap "Sign in with Google" (or another provider)
-   - Grant VPN permissions when prompted
-   - Toggle the connection ON
-
-3. **Get your Android's Tailscale IP:**
-   ```bash
-   # In Termux, run:
-   tailscale ip -4
-   # Example output: 100.100.100.100
-   ```
-
-   **OR** check in the Tailscale app:
-   - Open Tailscale app
-   - Your IP is shown under your device name (e.g., "100.100.100.100")
-
-#### Step 2: Install Tailscale on Server/Desktop
-
-**On Ubuntu/Debian:**
-```bash
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-```
-
-**On macOS:**
-```bash
-brew install tailscale
-sudo tailscale up
-```
-
-**On Windows:**
-- Download installer from https://tailscale.com/download/windows
-- Run installer and sign in
-
-**Get your server's Tailscale IP:**
-```bash
-tailscale ip -4
-# Example output: 100.100.100.101
-```
-
-#### Step 3: Configure SSH with Tailscale IP
-
-Update your `~/.ssh/config` to use the Tailscale IP instead of local WiFi IP:
-
-```ssh-config
-Host android
-    HostName 100.100.100.100    # ← Use Tailscale IP (from Step 1)
-    User u0_a123                # ← Your Termux username (run 'whoami' in Termux)
-    Port 8022
-    IdentityFile ~/.ssh/id_ed25519
-    ServerAliveInterval 60
-    ServerAliveCountMax 3
-```
-
-**Why this works everywhere:**
-- Tailscale IPs (100.x.x.x) are stable and work on ANY network
-- No need to change config when switching WiFi networks
-- Works even when Android is on mobile data
-
-#### Step 4: Test Connection
-
-```bash
-# Test from your server/desktop
-ssh android "echo 'Connected via Tailscale!'"
-
-# If successful, you're ready for AgentVibes
-```
-
-#### Benefits Summary
-
-| Without Tailscale | With Tailscale |
-|------------------|----------------|
-| Only works on same WiFi | Works from anywhere |
-| Need to update IP when network changes | Stable IP that never changes |
-| Port forwarding required | No configuration needed |
-| Insecure over internet | End-to-end encrypted |
-| Doesn't work on mobile data | Works on mobile data |
-
-**Recommendation:** Always use Tailscale for the best experience. It makes your Android device accessible from anywhere while keeping connections secure and private.
-
-### Multiple Android Devices
-
-Configure different host aliases:
-
-```ssh-config
-Host android-phone
-    HostName 100.100.100.100
-    User u0_a123
-    Port 8022
-
-Host android-tablet
-    HostName 100.100.100.101
-    User u0_a456
-    Port 8022
-```
-
-Then switch between them:
-```bash
-echo "android-tablet" > ~/.claude/termux-ssh-host.txt
-```
-
-### Custom TTS Voices
-
-Android TTS voices are managed in Android Settings, not AgentVibes:
-
-1. Open Android **Settings** → **Accessibility** → **Text-to-Speech**
-2. Install additional voice engines from Play Store (e.g., Google TTS, eSpeak)
-3. Select preferred engine and voice
-4. AgentVibes will use the selected voice automatically
-
-## Security Considerations
-
-- **SSH Key Authentication**: Always use SSH keys, never passwords
-- **Firewall**: Expose SSH port 8022 only on trusted networks
-- **VPN Recommended**: Use Tailscale/ZeroTier instead of public IPs
-- **No Sensitive Data**: Don't send sensitive information via TTS
-
-## How It Works
-
-```
-┌──────────────┐              ┌──────────────┐
-│   Desktop    │              │   Android    │
-│   (Server)   │              │   (Termux)   │
-└──────┬───────┘              └───────┬──────┘
-       │                               │
-       │  1. User runs command         │
-       │  .claude/hooks/play-tts.sh    │
-       │                               │
-       │  2. Route to termux-ssh       │
-       │     provider                  │
-       │                               │
-       │  3. SSH to Android            │
-       ├──────────────────────────────>│
-       │  ssh android "termux-tts-     │
-       │  speak 'text'"                │
-       │                               │
-       │                               │  4. Android TTS
-       │                               │     speaks text
-       │                               │     🔊
-       │                               │
-       │  5. Returns immediately       │
-       │<──────────────────────────────┤
-       │                               │
-       └───────────────────────────────┘
-```
-
-## Limitations
-
-- **Requires SSH connection**: Must be reachable via network
-- **No audio file output**: Provider outputs to remote device only
-- **Language support**: Limited to Android TTS engine capabilities
-- **Network latency**: Adds ~100-500ms depending on connection
-
-## See Also
-
-- [Provider Management](../commands/agent-vibes/provider.md)
-- [Voice Configuration](../commands/agent-vibes/voice.md)
-- [SSH Configuration Guide](https://www.ssh.com/academy/ssh/config)
-- [Termux Wiki](https://wiki.termux.com/)
+# Termux SSH TTS Provider Setup Guide
+
+## Overview
+
+The `termux-ssh` provider allows AgentVibes to send TTS audio output to your Android device when you're connected from Termux via SSH. Instead of playing audio locally on your server/desktop, text is sent to your phone via SSH and spoken using Android's native TTS engine (`termux-tts-speak`).
+
+**Use Case:** You're working on a remote server (VPS, cloud instance, home server) and want to hear AgentVibes TTS on your Android phone instead of the server's speakers.
+
+### Why This Provider?
+
+- **Solves PulseAudio issues**: PulseAudio tunneling doesn't work reliably on Android/Termux
+- **Uses native Android TTS**: High-quality voices from Google TTS or other installed engines
+- **Near-instant**: Only sends text, not audio files
+- **Works from anywhere**: With Tailscale, access your Android from any network
+- **No configuration overhead**: Works with standard SSH setup
+
+## Prerequisites
+
+> **💡 Tip:** Install Tailscale first (see [Advanced Configuration](#using-tailscale-for-internet-wide-access-recommended)) for the best experience. It allows you to access your Android device from anywhere, not just your local WiFi.
+
+### On Android Device (Termux)
+
+1. **Install Termux** from F-Droid (NOT Google Play - it's outdated)
+   ```bash
+   # Download from: https://f-droid.org/en/packages/com.termux/
+   ```
+
+2. **Install required packages**:
+   ```bash
+   pkg update
+   pkg install termux-api openssh
+   ```
+
+3. **Install Termux:API app** from F-Droid:
+   ```bash
+   # Download from: https://f-droid.org/en/packages/com.termux.api/
+   ```
+
+4. **Start SSH server**:
+   ```bash
+   # Generate SSH keys (first time only)
+   ssh-keygen -t rsa -b 4096
+
+   # Start SSH daemon
+   sshd
+
+   # Find your SSH port (usually 8022)
+   cat $PREFIX/var/run/sshd.pid
+   ```
+
+5. **Get your device IP address**:
+
+   **Option A: Tailscale IP (Recommended)**
+   ```bash
+   # After installing Tailscale (see Advanced Configuration)
+   tailscale ip -4
+   # Example: 100.100.100.100
+   ```
+
+   **Option B: Local WiFi IP (Same Network Only)**
+   ```bash
+   # Only works when both devices are on the same WiFi
+   ifconfig wlan0 | grep "inet addr"
+   # Example: 192.168.1.100
+   ```
+
+   > ⚠️ **Local WiFi IPs only work on the same network.** Use Tailscale for reliable access from anywhere.
+
+### On Server/Desktop
+
+1. **Copy SSH public key to Android**:
+   ```bash
+   # On your desktop/server
+   ssh-copy-id -p 8022 u0_a###@<android-ip>
+
+   # Replace:
+   # - u0_a### with your Termux username (run 'whoami' in Termux)
+   # - <android-ip> with your Android device IP
+   ```
+
+2. **Configure SSH host alias** in `~/.ssh/config`:
+   ```ssh-config
+   Host android
+       HostName <your-android-ip>
+       User <your-termux-username>
+       Port 8022
+       IdentityFile ~/.ssh/id_rsa
+       ServerAliveInterval 60
+       ServerAliveCountMax 3
+   ```
+
+   **Example**:
+   ```ssh-config
+   Host android
+       HostName 100.100.100.100    # Tailscale IP
+       User u0_a123                # From 'whoami' in Termux
+       Port 8022
+       IdentityFile ~/.ssh/id_ed25519
+       ServerAliveInterval 60
+   ```
+
+3. **Test SSH connection**:
+   ```bash
+   ssh android "echo 'Connection successful!'"
+   ```
+
+## AgentVibes Configuration
+
+### 1. Set SSH Host Alias
+
+Choose ONE of these methods:
+
+**Option A: Environment Variable** (Temporary)
+```bash
+export TERMUX_SSH_HOST="android"
+```
+
+**Option B: Global Config File** (Recommended)
+```bash
+echo "android" > ~/.claude/termux-ssh-host.txt
+```
+
+**Option C: Project-Specific**
+```bash
+echo "android" > /path/to/project/.claude/termux-ssh-host.txt
+```
+
+### 2. Switch to termux-ssh Provider
+
+```bash
+# Using slash command (in Claude Code)
+/agent-vibes:provider switch termux-ssh
+
+# Or manually
+echo "termux-ssh" > ~/.claude/tts-provider.txt
+```
+
+### 3. Verify Setup
+
+```bash
+# List available providers (should include termux-ssh)
+/agent-vibes:provider list
+
+# Check active provider
+/agent-vibes:provider get
+
+# Test TTS
+.claude/hooks/play-tts.sh "Testing Android TTS via SSH"
+```
+
+## Usage
+
+Once configured, AgentVibes will automatically route TTS to your Android device:
+
+```bash
+# TTS plays on your Android phone, not the server
+.claude/hooks/play-tts.sh "This will play on my Android device"
+```
+
+## Troubleshooting
+
+### "Cannot connect to SSH host 'android'"
+
+**Possible causes**:
+1. SSH server not running on Android: `sshd` in Termux
+2. Wrong IP/hostname in ~/.ssh/config
+3. Firewall blocking port 8022
+4. Android device not on same network (or no VPN connection)
+
+**Debug**:
+```bash
+# Test SSH connection manually
+ssh android "echo ok"
+
+# Check SSH config
+cat ~/.ssh/config | grep -A5 "Host android"
+
+# Verify sshd is running on Android
+ssh android "ps aux | grep sshd"
+```
+
+### "termux-tts-speak: command not found"
+
+**Solution**:
+```bash
+# On Android (Termux)
+pkg install termux-api
+
+# Verify installation
+which termux-tts-speak
+```
+
+### "Provider 'termux-ssh' not found"
+
+**Solution**:
+```bash
+# Verify provider file exists
+ls -la .claude/hooks/play-tts-termux-ssh.sh
+
+# Check if executable
+chmod +x .claude/hooks/play-tts-termux-ssh.sh
+
+# List providers to confirm
+/agent-vibes:provider list
+```
+
+### Audio plays but very slow/delayed
+
+This is normal for the first invocation. Subsequent calls should be instant.
+
+**Optimization**:
+```bash
+# Add ControlMaster to ~/.ssh/config for connection pooling
+Host android
+    ControlMaster auto
+    ControlPath ~/.ssh/sockets/%r@%h-%p
+    ControlPersist 10m
+```
+
+## Advanced Configuration
+
+### Using Tailscale for Internet-Wide Access (Recommended)
+
+#### Why Use Tailscale?
+
+**The Problem:**
+- Your Android device and server are on different networks (home WiFi, mobile data, office)
+- SSH requires both devices on the same local network OR a public IP with port forwarding
+- Port forwarding is complex, insecure, and often blocked by carriers/ISPs
+- Public WiFi networks block SSH connections
+
+**The Solution: Tailscale**
+
+Tailscale creates a secure, private VPN network between your devices that works from anywhere:
+- ✅ Access your Android from any network (home, office, coffee shop, mobile data)
+- ✅ No port forwarding or firewall configuration needed
+- ✅ Encrypted point-to-point connections
+- ✅ Works behind NAT, firewalls, and on mobile data
+- ✅ Free for personal use (up to 100 devices)
+- ✅ Each device gets a stable private IP (100.x.x.x)
+
+#### Step 1: Install Tailscale on Android
+
+1. **Download Tailscale from Play Store:**
+   - Search for "Tailscale" in Google Play Store
+   - Install the official Tailscale app
+   - OR download APK from: https://tailscale.com/download/android
+
+2. **Connect to Tailscale:**
+   - Open Tailscale app
+   - Tap "Sign in with Google" (or another provider)
+   - Grant VPN permissions when prompted
+   - Toggle the connection ON
+
+3. **Get your Android's Tailscale IP:**
+   ```bash
+   # In Termux, run:
+   tailscale ip -4
+   # Example output: 100.100.100.100
+   ```
+
+   **OR** check in the Tailscale app:
+   - Open Tailscale app
+   - Your IP is shown under your device name (e.g., "100.100.100.100")
+
+#### Step 2: Install Tailscale on Server/Desktop
+
+**On Ubuntu/Debian:**
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+```
+
+**On macOS:**
+```bash
+brew install tailscale
+sudo tailscale up
+```
+
+**On Windows:**
+- Download installer from https://tailscale.com/download/windows
+- Run installer and sign in
+
+**Get your server's Tailscale IP:**
+```bash
+tailscale ip -4
+# Example output: 100.100.100.101
+```
+
+#### Step 3: Configure SSH with Tailscale IP
+
+Update your `~/.ssh/config` to use the Tailscale IP instead of local WiFi IP:
+
+```ssh-config
+Host android
+    HostName 100.100.100.100    # ← Use Tailscale IP (from Step 1)
+    User u0_a123                # ← Your Termux username (run 'whoami' in Termux)
+    Port 8022
+    IdentityFile ~/.ssh/id_ed25519
+    ServerAliveInterval 60
+    ServerAliveCountMax 3
+```
+
+**Why this works everywhere:**
+- Tailscale IPs (100.x.x.x) are stable and work on ANY network
+- No need to change config when switching WiFi networks
+- Works even when Android is on mobile data
+
+#### Step 4: Test Connection
+
+```bash
+# Test from your server/desktop
+ssh android "echo 'Connected via Tailscale!'"
+
+# If successful, you're ready for AgentVibes
+```
+
+#### Benefits Summary
+
+| Without Tailscale | With Tailscale |
+|------------------|----------------|
+| Only works on same WiFi | Works from anywhere |
+| Need to update IP when network changes | Stable IP that never changes |
+| Port forwarding required | No configuration needed |
+| Insecure over internet | End-to-end encrypted |
+| Doesn't work on mobile data | Works on mobile data |
+
+**Recommendation:** Always use Tailscale for the best experience. It makes your Android device accessible from anywhere while keeping connections secure and private.
+
+### Multiple Android Devices
+
+Configure different host aliases:
+
+```ssh-config
+Host android-phone
+    HostName 100.100.100.100
+    User u0_a123
+    Port 8022
+
+Host android-tablet
+    HostName 100.100.100.101
+    User u0_a456
+    Port 8022
+```
+
+Then switch between them:
+```bash
+echo "android-tablet" > ~/.claude/termux-ssh-host.txt
+```
+
+### Custom TTS Voices
+
+Android TTS voices are managed in Android Settings, not AgentVibes:
+
+1. Open Android **Settings** → **Accessibility** → **Text-to-Speech**
+2. Install additional voice engines from Play Store (e.g., Google TTS, eSpeak)
+3. Select preferred engine and voice
+4. AgentVibes will use the selected voice automatically
+
+## Security Considerations
+
+- **SSH Key Authentication**: Always use SSH keys, never passwords
+- **Firewall**: Expose SSH port 8022 only on trusted networks
+- **VPN Recommended**: Use Tailscale/ZeroTier instead of public IPs
+- **No Sensitive Data**: Don't send sensitive information via TTS
+
+## How It Works
+
+```
+┌──────────────┐              ┌──────────────┐
+│   Desktop    │              │   Android    │
+│   (Server)   │              │   (Termux)   │
+└──────┬───────┘              └───────┬──────┘
+       │                               │
+       │  1. User runs command         │
+       │  .claude/hooks/play-tts.sh    │
+       │                               │
+       │  2. Route to termux-ssh       │
+       │     provider                  │
+       │                               │
+       │  3. SSH to Android            │
+       ├──────────────────────────────>│
+       │  ssh android "termux-tts-     │
+       │  speak 'text'"                │
+       │                               │
+       │                               │  4. Android TTS
+       │                               │     speaks text
+       │                               │     🔊
+       │                               │
+       │  5. Returns immediately       │
+       │<──────────────────────────────┤
+       │                               │
+       └───────────────────────────────┘
+```
+
+## Limitations
+
+- **Requires SSH connection**: Must be reachable via network
+- **No audio file output**: Provider outputs to remote device only
+- **Language support**: Limited to Android TTS engine capabilities
+- **Network latency**: Adds ~100-500ms depending on connection
+
+## See Also
+
+- [Provider Management](../commands/agent-vibes/provider.md)
+- [Voice Configuration](../commands/agent-vibes/voice.md)
+- [SSH Configuration Guide](https://www.ssh.com/academy/ssh/config)
+- [Termux Wiki](https://wiki.termux.com/)