agentwire-dev 1.1.0

Multi-session voice web interface for AI coding agents

Multi-session voice web interface for AI coding agents

---

Push-to-talk voice input from any device to tmux sessions running Claude Code or any AI coding assistant.

Features

• Desktop Control Center - WinBox-powered window management with draggable/resizable session windows
• Session Windows - Monitor mode (read-only output) or Terminal mode (full xterm.js) per session
• Push-to-Talk Voice - Hold to speak, release to send transcription from any device
• TTS Playback - Agent responses spoken back via browser audio with smart routing
• Multi-Device Access - Control sessions from phone, tablet, or laptop on your network
• Git Worktrees - Multiple agents work the same project in parallel on separate branches
• Remote Machines - Orchestrate Claude Code sessions on remote servers via SSH
• Safety Hooks - 300+ dangerous command patterns blocked (rm -rf, git push --force, secret exposure)
• Session Roles - Orchestrator sessions coordinate voice, workers execute focused tasks
• Permission Hooks - Claude Code integration for permission dialogs in the portal

What's New

v1.0.0 (January 2026):

• Desktop Control Center with WinBox-based window management
• Safety hooks with 300+ dangerous command patterns blocked
• Git worktree support for parallel agent work
• Session roles (orchestrator/worker) for coordinated workflows
• Voice cloning support with custom TTS voices
• Remote machine orchestration via SSH tunnels

Quick Start

System Requirements

Before installing, ensure you have:

Requirement	Minimum	Check
Claude Code OR OpenCode	Any recent	claude --version or opencode --version
Python	3.10+	python3 --version
tmux	Any recent	tmux -V
ffmpeg	Any recent	ffmpeg -version

Important for Ubuntu 24.04+ users: Ubuntu's externally-managed Python requires using a virtual environment. See the Ubuntu installation instructions below.

Platform-Specific Installation

macOS:

# Install dependencies
brew install tmux ffmpeg

# If Python < 3.10, upgrade via pyenv
brew install pyenv
pyenv install 3.12.0
pyenv global 3.12.0

# Install AgentWire
pip install agentwire-dev

Ubuntu/Debian:

# Install dependencies
sudo apt update
sudo apt install tmux ffmpeg python3-pip

# For Ubuntu 24.04+ (recommended approach):
# Create venv to avoid externally-managed error
python3 -m venv ~/.agentwire-venv
source ~/.agentwire-venv/bin/activate
echo 'source ~/.agentwire-venv/bin/activate' >> ~/.bashrc

# Install AgentWire
pip install agentwire-dev

WSL2:

# Same as Ubuntu
sudo apt install tmux ffmpeg python3-pip
pip install agentwire-dev

# Note: Audio support limited in WSL
# Recommended: Use as remote worker with portal on Windows host

Setup & Run

# Interactive setup (configures audio, creates config)
agentwire init

# Generate SSL certs (required for browser mic access)
agentwire generate-certs

# Start the portal
agentwire portal start

# Open in browser
# https://localhost:8765

Optional: Configure OpenCode as your AI agent:

# Install OpenCode
npm install -g @opencode-ai/cli

# Configure AgentWire to use OpenCode
cat > ~/.agentwire/config.yaml << 'EOF'
agent:
  command: "opencode"
EOF

Expected Install Time:

• First time: 20-30 minutes (including dependency installation, configuration)
• Subsequent installs: 5 minutes (if dependencies already present)

Common First-Time Issues

Issue	Solution
"Python 3.X.X not in '>=3.10'"	Upgrade Python (see platform instructions above)
"externally-managed-environment" (Ubuntu)	Use venv approach (see Ubuntu instructions above)
"agentwire: command not found"	Add to PATH: export PATH="$HOME/.local/bin:$PATH"
"ffmpeg not found"	Install ffmpeg (see platform commands above)
SSL warnings in browser	Run agentwire generate-certs, then accept cert in browser

Full troubleshooting guide: See docs/TROUBLESHOOTING.md after installation

CLI Commands

# Setup & Diagnostics
agentwire init              # Interactive setup wizard
agentwire generate-certs    # Generate SSL certificates
agentwire doctor            # Auto-diagnose and fix common issues
agentwire network status    # Check service health

# Portal (web server)
agentwire portal start      # Start in background (tmux)
agentwire portal stop       # Stop the portal
agentwire portal status     # Check if running

# TTS Server (self-hosted, requires GPU)
agentwire tts start         # Start local TTS server
agentwire tts stop          # Stop TTS server
agentwire tts status        # Check if running

# STT Server (speech-to-text)
agentwire stt start         # Start STT server
agentwire stt stop          # Stop STT server
agentwire stt status        # Check if running

# Voice
agentwire say "Hello"              # Speak (auto-routes to browser or local)
agentwire say -s api "Done"        # Send TTS to specific session
agentwire alert "Status update"    # Text notification to parent (no audio)
agentwire alert --to main "Done"   # Text notification to specific session
agentwire listen start             # Start recording voice input
agentwire listen stop              # Stop and send transcription

# Voice Cloning
agentwire voiceclone start         # Start recording voice sample
agentwire voiceclone stop name     # Stop and upload as voice clone
agentwire voiceclone list          # List available voices
agentwire voiceclone delete name   # Delete a voice clone

# Session Management
agentwire list                         # List all tmux sessions
agentwire new -s <name> [-p path] [-f] # Create new Claude session
agentwire output -s <session> [-n 100] # Read session output
agentwire info -s <session>            # Get session info (cwd, panes)
agentwire kill -s <session>            # Kill session (clean shutdown)
agentwire send -s <session> "prompt"   # Send prompt to session
agentwire send-keys -s <session> keys  # Send raw keys (with pauses)
agentwire recreate -s <session>        # Destroy and recreate session
agentwire fork -s <session>            # Fork into new worktree

# Pane Management (workers)
agentwire spawn --roles worker    # Spawn worker pane in current session
agentwire split -s <session>      # Add terminal pane(s)
agentwire jump --pane <N>         # Focus a pane
agentwire detach -s <session>     # Move pane to its own session
agentwire resize -s <session>     # Resize window to fit largest client

# Safety & Security
agentwire safety check "command"  # Test if command would be blocked
agentwire safety status           # Show pattern counts and recent blocks
agentwire safety logs --tail 20   # Query audit logs
agentwire safety install          # Install damage control hooks
agentwire hooks install           # Install Claude Code permission hook
agentwire hooks uninstall         # Remove Claude Code permission hook
agentwire hooks status            # Check hook installation status

# Remote Machines & Tunnels
agentwire machine list            # List registered machines
agentwire machine add <id>        # Add a machine
agentwire machine remove <id>     # Remove a machine
agentwire tunnels up              # Create SSH tunnels for services
agentwire tunnels down            # Tear down tunnels
agentwire tunnels status          # Check tunnel health

# Session History
agentwire history list            # List conversation history
agentwire history show <id>       # Show session details
agentwire history resume <id>     # Resume session (forks)

# Roles & Projects
agentwire roles list              # List available roles
agentwire roles show <name>       # Show role details
agentwire projects list           # Discover projects

# Development
agentwire dev                     # Start agentwire session
agentwire rebuild                 # Reinstall from source
agentwire uninstall               # Uninstall the tool

Configuration

Run agentwire init for interactive setup, or create ~/.agentwire/config.yaml:

server:
  host: "0.0.0.0"
  port: 8765

projects:
  dir: "~/projects"
  worktrees:
    enabled: true

tts:
  backend: "runpod"  # runpod | chatterbox | none
  runpod_endpoint_id: "your-endpoint-id"
  runpod_api_key: "your-api-key"

agent:
  command: "claude --dangerously-skip-permissions"  # or "opencode"

Project configuration: Create .agentwire.yml in your project directory:

type: "standard"  # Universal session type
roles:
  - agentwire

Session Types

AgentWire supports multiple AI agents and session types:

Universal Types (Recommended)

• standard - Full automation, no permission prompts
• worker - No AskUserQuestion, no voice, focused execution
• voice - Voice with permission prompts, user approval
• bare - Terminal only, no agent

Agent-Specific Types

• Claude Code: claude-bypass, claude-prompted, claude-restricted
• OpenCode: opencode-bypass, opencode-prompted, opencode-restricted

Simple Session

myapp -> ~/projects/myapp/

Single agent working on a project.

Worktree Session

myapp/feature-auth -> ~/projects/myapp-worktrees/feature-auth/

Multiple agents working on the same project in parallel, each on their own branch.

Remote Session

ml@gpu-server -> SSH to gpu-server, session "ml"

Agent running on a remote machine.

Safety & Security

AgentWire includes damage control hooks that protect against dangerous operations across all sessions (both Claude Code and OpenCode).

What's Protected

300+ dangerous command patterns:

• Destructive operations: rm -rf, git push --force, git reset --hard
• Cloud platforms: AWS, GCP, Firebase, Vercel, Netlify, Cloudflare
• Databases: SQL DROP/TRUNCATE, Redis FLUSHALL, MongoDB dropDatabase
• Containers: Docker/Kubernetes destructive operations
• Infrastructure: Terraform destroy, Pulumi destroy

Sensitive file protection:

• Zero-access paths (no operations): .env, SSH keys, credentials, API tokens
• Read-only paths: System configs, lock files
• No-delete paths: .git/, README.md, mission files

Usage

# Test if command would be blocked
agentwire safety check "rm -rf /tmp"
# → ✗ Decision: BLOCK (rm with recursive or force flags)

# Check system status
agentwire safety status
# → Shows pattern counts, recent blocks, audit log location

# Query audit logs
agentwire safety logs --tail 20
# → Shows recent blocked/allowed operations with timestamps

# Install hooks (first time setup)
agentwire safety install

How It Works

PreToolUse hooks intercept Bash, Edit, and Write operations before execution:

• Blocked → Operation prevented, security message shown
• Allowed → Operation proceeds normally
• Ask → User confirmation required (for risky but valid operations)

All decisions are logged to ~/.agentwire/logs/damage-control/ for audit trails.

Voice Integration

AgentWire provides TTS via the agentwire say command with automatic audio routing:

# In sessions, Claude (or users) can trigger TTS:
agentwire say "Hello world"  # Automatically routes to browser or local speakers

How it works:

• agentwire say automatically detects if a browser is connected to the session
• If connected: streams audio to browser (tablet/phone/laptop)
• If not connected: plays audio locally (Mac speakers)
• Session detection uses AGENTWIRE_SESSION env var (set automatically when session is created)
• For remote machines, configure portal URL in ~/.agentwire/portal_url

TTS requires a GPU server running Chatterbox. We recommend RunPod:

# In config.yaml
tts:
  backend: "runpod"
  runpod_endpoint_id: "your-endpoint-id"
  runpod_api_key: "your-api-key"

See docs/runpod-tts.md for RunPod setup, or use agentwire tts start if self-hosting on your own GPU.

Or run with TTS disabled (text-only):

tts:
  backend: "none"

STT (Speech-to-Text)

Default (macOS): STT runs locally using WhisperKit (Apple's CoreML-optimized Whisper). Fast and private - no server needed.

Requirements for local STT:

• macOS with Apple Silicon (M1/M2/M3)
• whisperkit-cli: brew install whisperkit-cli
• A WhisperKit model (e.g., via MacWhisper)

Default model path: ~/Library/Application Support/MacWhisper/models/whisperkit/models/argmaxinc/whisperkit-coreml/openai_whisper-large-v3-v20240930

Alternative (Linux/cross-platform): Run the STT server with faster-whisper:

pip install agentwire-dev[stt]
agentwire stt start

Architecture

Phone/Tablet ──► AgentWire Portal ──► tmux session
   (voice)          (WebSocket)         (Claude Code)
     │                   │                    │
     │    push-to-talk   │   transcription    │
     │◄─────────────────►│◄──────────────────►│
     │    TTS audio      │   agent output     │

Development

# Clone
git clone https://github.com/dotdevdotdev/agentwire-dev
cd agentwire-dev

# Install with uv
uv venv && uv pip install -e .

# Run in dev mode (picks up source changes)
agentwire portal start --dev

# After structural changes (pyproject.toml, new files)
agentwire rebuild

Contributing

Contributions welcome! Please open an issue first to discuss changes.

• Report bugs
• Request features

Documentation

• docs/TROUBLESHOOTING.md - Common issues and solutions
• docs/PORTAL.md - Portal modes and API
• docs/remote-machines.md - Multi-machine setup
• docs/runpod-tts.md - RunPod TTS setup
• docs/tts-self-hosted.md - Self-hosted TTS
• docs/security/damage-control.md - Safety hooks

License

AgentWire is dual-licensed:

• Open Source: AGPL v3 - Free for open source projects
• Commercial: Contact us for a commercial license if AGPL doesn't work for your use case

See CLA.md for contributor agreement.