verbalcoding 0.2.11 → 0.2.13

package/.env.example

@@ -1,17 +1,44 @@
 # Copy to .env and fill local values. Do not commit .env.
+# Preferred setup commands:
+#   vc setup token
+#   vc setup channels "General,Team Voice"
 
 DISCORD_BOT_TOKEN=""
+DISCORD_CLIENT_ID=""
 DISCORD_ALLOWED_USERS=""
 AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
 TRANSCRIPT_CHANNEL_ID=""
+VOICE_CONNECT_TIMEOUT_MS="60000"
 
-# Agent harness: hermes, claude-code, claude, codex, gemini, opencode, openclaw, custom
+# Agent harness: hermes, claude-code, claude, codex, gemini, opencode, openclaw, aider, cursor, custom
+# `vc setup` auto-detects which agents are installed and lets you pick.
 AGENT_BACKEND="hermes"
 # AGENT_LABEL="My Harness"
 # AGENT_COMMAND="my-harness run --non-interactive"
+# AIDER_COMMAND="aider --no-pretty --yes-always --message"
+# CURSOR_COMMAND="cursor-agent --print --prompt"
 AGENT_TASK_TIMEOUT_MS="0"
 AGENT_CHAT_TIMEOUT_MS="45000"
 AGENT_VERBOSE_PROGRESS="0"   # default off; toggle in Discord with !verbose on/off
+
+# Streaming TTS pipeline: sentence-by-sentence playback while the agent is still writing.
+# First audio plays before the agent finishes. Set to "0" to fall back to whole-reply playback.
+STREAMING_TTS="1"
+
+# Smart progress summarization. When SMART_PROGRESS_API_KEY is set, raw progress events get
+# folded into a single human sentence via a small LLM (Groq OpenAI-compatible API by default).
+# Without an API key it falls back to the existing regex categories.
+# SMART_PROGRESS_API_KEY=""
+# SMART_PROGRESS_BASE_URL="https://api.groq.com/openai/v1"
+# SMART_PROGRESS_MODEL="llama-3.1-8b-instant"
+
+# Push notification handoff for long tasks when the voice channel is empty.
+# Provider: ntfy (free, no account, mobile apps) | pushover | noop.
+# NOTIFY_PROVIDER="ntfy"
+# NTFY_TOPIC=""                  # pick something unguessable; subscribe with the ntfy app
+# PUSHOVER_USER=""
+# PUSHOVER_TOKEN=""
+NOTIFY_MIN_TASK_MS="60000"      # only notify when a task ran at least this long
 LATENCY_LOG_PATH="./.logs/latency.jsonl"
 PROJECT_SESSIONS_FILE="./config/project-sessions.json"
 # Agent workflow helper: off by default. Toggle with `vc restart auto on|off`.
@@ -24,7 +51,7 @@ VOICE_LANGUAGE="ko"        # ko | en | auto; controls progress/status language
 WHISPER_CPP_LANGUAGE="ko"  # ko | en | auto; auto omits forced whisper language
 STT_LANGUAGE="ko"
 
-TTS_BACKEND="edge"   # edge | openvoice | speechswift | supertonic
+TTS_BACKEND="edge"   # edge | openvoice | speechswift | supertonic | omnivoice | qwen3tts | mlxaudio | fireredtts2 | mossttsnano | neuttsair
 EDGE_TTS_COMMAND="edge-tts"
 TTS_VOICE_TYPE="korean_female"  # edge: korean_male | korean_female | korean_multilingual_male | english_male | english_female
 TTS_VOICE="ko-KR-SunHiNeural"
@@ -66,6 +93,33 @@ OPENVOICE_LANGUAGE="KR"
 OPENVOICE_STYLE="default"
 OPENVOICE_TIMEOUT_MS="90000"
 OPENVOICE_PROGRESS="0"   # keep progress prompts fast via Edge unless set to 1
+
+# Optional k2-fsa/OmniVoice TTS backend (600+ language zero-shot TTS / voice cloning).
+# Recommended: create a separate env, install torch/torchaudio/soundfile/omnivoice, and keep progress prompts on Edge.
+OMNIVOICE_PYTHON="./.venv-omnivoice/bin/python"
+OMNIVOICE_MODEL="k2-fsa/OmniVoice"
+OMNIVOICE_DEVICE="mps"       # mps on Apple Silicon, cuda:0 on NVIDIA, cpu as fallback
+OMNIVOICE_DTYPE="float16"
+OMNIVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
+OMNIVOICE_REF_TEXT=""        # optional transcript of the reference sample
+OMNIVOICE_LANGUAGE="ko"
+OMNIVOICE_SPEAKER=""         # optional voice-design attributes when no ref sample is desired
+OMNIVOICE_TIMEOUT_MS="180000"
+OMNIVOICE_PROGRESS="0"       # keep progress prompts fast via Edge unless set to 1
+
+# Optional Qwen3-TTS CLI backend via speech-swift `audio speak`.
+# Install speech-swift/audio separately, then set TTS_BACKEND="qwen3tts" or "qwen3".
+QWEN3TTS_COMMAND="audio"
+QWEN3TTS_MODE="custom"       # custom | clone | design
+QWEN3TTS_MODEL="customVoice" # customVoice for preset speakers, base/base-8bit for cloning
+QWEN3TTS_LANGUAGE="korean"
+QWEN3TTS_SPEAKER="sohee"    # used in custom mode
+QWEN3TTS_INSTRUCT=""         # emotion/style instruction; used in custom/design modes
+QWEN3TTS_REF_AUDIO="./voice-samples/user-reference.wav"  # used in clone mode
+QWEN3TTS_REF_TEXT=""         # optional note for your reference sample
+QWEN3TTS_STREAM="1"
+QWEN3TTS_TIMEOUT_MS="120000"
+QWEN3TTS_PROGRESS="0"        # keep progress prompts fast via Edge unless set to 1
 REQUIRE_WAKE_WORD="0"
 MIN_UTTERANCE_SECONDS="1.0"
 # Wait for natural thinking pauses before STT. Lower for faster but more fragmented turns.
@@ -83,3 +137,45 @@ BARGE_IN_CONSERVATIVE_MIN_SECONDS="1.8"
 BARGE_IN_CONSERVATIVE_MIN_MEAN_VOLUME_DB="-27"
 BARGE_IN_CONSERVATIVE_MIN_MAX_VOLUME_DB="-12"
 MAX_DEFERRED_PROCESSING_UTTERANCES="0"
+
+
+# Optional local TTS backends (final answers only by default; progress falls back to Edge)
+# TTS_BACKEND=fireredtts2
+FIREREDTTS2_COMMAND=./.local/bin/fireredtts2
+FIREREDTTS2_PRETRAINED_DIR=pretrained_models/FireRedTTS2
+FIREREDTTS2_DEVICE=auto
+FIREREDTTS2_GEN_TYPE=monologue
+FIREREDTTS2_SPEAKER=S1
+FIREREDTTS2_PROMPT_AUDIO=voice-samples/user-reference.wav
+FIREREDTTS2_PROMPT_TEXT=
+FIREREDTTS2_BF16=0
+FIREREDTTS2_TIMEOUT_MS=180000
+FIREREDTTS2_PROGRESS=0
+
+# TTS_BACKEND=mossttsnano
+MOSSTTSNANO_COMMAND=python3
+MOSSTTSNANO_SCRIPT=vendor/MOSS-TTS-Nano/infer.py
+MOSSTTSNANO_CHECKPOINT=OpenMOSS-Team/MOSS-TTS-Nano
+MOSSTTSNANO_AUDIO_TOKENIZER=
+MOSSTTSNANO_MODE=continuation
+MOSSTTSNANO_DEVICE=auto
+MOSSTTSNANO_DTYPE=auto
+MOSSTTSNANO_PROMPT_AUDIO=voice-samples/user-reference.wav
+MOSSTTSNANO_PROMPT_TEXT=
+MOSSTTSNANO_MAX_NEW_FRAMES=375
+MOSSTTSNANO_TIMEOUT_MS=120000
+MOSSTTSNANO_PROGRESS=0
+
+# TTS_BACKEND=neuttsair  # NeuTTS Air is English-only; progress falls back to Edge by default.
+NEUTTSAIR_PYTHON=./.venv-neuttsair/bin/python
+NEUTTSAIR_SCRIPT=integrations/neuttsair/synth.py
+NEUTTSAIR_BACKBONE_REPO=neuphonic/neutts-air-q4-gguf
+NEUTTSAIR_BACKBONE_DEVICE=mps
+NEUTTSAIR_CODEC_REPO=neuphonic/neucodec
+NEUTTSAIR_CODEC_DEVICE=mps
+NEUTTSAIR_REF_AUDIO=voice-samples/user-reference.wav
+NEUTTSAIR_REF_TEXT=
+NEUTTSAIR_LANGUAGE=en
+NEUTTSAIR_SAMPLE_RATE=24000
+NEUTTSAIR_TIMEOUT_MS=120000
+NEUTTSAIR_PROGRESS=0

package/README.es.md

@@ -0,0 +1,134 @@
+# VerbalCoding
+
+<p align="center"><strong>Habla con agentes de programación CLI por voz en Discord, como en una llamada.</strong></p>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.zh.md">中文</a> · <a href="./README.fr.md">Français</a> · <a href="./README.ru.md">Русский</a></p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Por qué existe
+
+VerbalCoding convierte una sala de voz de Discord en una cabina manos libres para agentes de programación. Pides algo hablando, dejas trabajar al agente CLI y recibes una respuesta breve por voz con transcripción y eventos de progreso. Los diffs y logs quedan fuera del TTS largo.
+
+> **¿Ya usas Hermes Agent?** Hermes ya trae soporte de canales de voz de Discord con `/voice join` / `/voice channel`: puede unirse al VC actual, transcribir con Whisper y responder por TTS. Para ese bucle básico, VerbalCoding no es obligatorio. VerbalCoding añade una capa de flujo de trabajo: enrutamiento de proyectos/sesiones, contexto compartido de voz+texto, reglas de interrupción, avisos de progreso, presets de idioma, métricas de latencia y cambio de backend CLI más allá de Hermes.
+
+## Qué lo hace distinto
+
+| Capacidad | Por qué importa |
+|---|---|
+| Flujo tipo llamada | Habla, escucha, interrumpe y continúa en el mismo canal de voz de Discord. |
+| Configuración guiada | `vc setup` reúne prerequisites, Discord token/client ID, voice channel, transcript target, backend y TTS settings en un solo flujo. |
+| Bucle de voz local | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
+| Elección de agente | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI o custom command. `vc setup` autodetecta lo que tienes instalado. |
+| Enrutamiento de agente por voz | `"ask Codex what it thinks"` (un turno), `"switch to Aider"` (sticky), `"back to default"` para volver. Si el binario no está instalado, el puente ofrece fallback al agente por defecto. |
+| Más allá de la voz integrada de Hermes | Mantiene el mismo bucle de voz en VC y añade salas de proyecto, contexto compartido con `!ask`, interrupciones afinadas, voz de progreso/estado y control de backends multiagente. |
+| Operación real | Incluye doctor auto-fix, guía Docker UDP, latency metrics, multi-instance rooms y redacted config checks. |
+
+## Inicio rápido
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+`vc setup` es la ruta normal para personas. Mantén abierto Discord Developer Portal mientras introduces bot token, application/client ID, transcript target y voice channel names.
+
+En automatización puedes omitir prompts y completar los datos de Discord después.
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## Discord en un minuto
+
+1. Crea una application y un bot en Discord Developer Portal.
+2. Activa Message Content privileged intent.
+3. Ejecuta `vc setup` y pega bot token y application/client ID.
+4. Introduce los nombres exactos de los voice channels para auto-join.
+5. Invita el bot con estos comandos.
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## Mapa mínimo de comandos
+
+```bash
+vc setup                                 # configuración guiada: prerequisites, Discord, backend, voice
+vc setup --yes                           # bootstrap/starter config no interactiva
+vc setup token                           # rotar o añadir Discord bot token/client ID después
+vc setup channels "General,Team Voice"   # actualizar auto-join voice channel names
+vc bot invite CLIENT_ID                  # generar Discord bot invite URL
+vc status                                # mostrar configuración actual
+vc language ko|en|auto                   # cambiar language preset
+vc doctor                                # redacted health check y auto-fixes
+vc start                                 # iniciar bridge por defecto
+vc instance setup NAME                   # crear project voice bot aislado
+vc instance start NAME                   # ejecutar ese bot en background
+```
+
+## Más información
+
+| Guía | Qué obtienes |
+|---|---|
+| [Centro de documentación](docs/i18n/README.es.md) | Índice de guías localizadas. |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.es.md) | npm/global setup, configuración de Discord y primera ejecución. |
+| [Usage](docs/i18n/USAGE.es.md) | Comandos CLI, comandos Discord, modos de ejecución y latency. |
+| [Uso por harness](docs/i18n/HARNESSES.es.md) | Instalación, configuración y enrutamiento por voz para Claude Code, Codex, Aider y demás. |
+| [Voz integrada de Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.es.md) | La voz Discord que Hermes ya ofrece y la diferencia de VerbalCoding. |
+| [Configuration](docs/i18n/CONFIGURATION.es.md) | .env, agent backends, MCP, TTS y operación. |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.es.md) | Docker UDP y comprobaciones de token/channel. |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.es.md) | Una sala de voz fija por proyecto. |
+
+## Requisitos
+
+| Capa | Predeterminado |
+|---|---|
+| Runtime | Node.js 20+ y npm. |
+| Audio | `ffmpeg` y local `whisper-cli`. |
+| TTS | Edge TTS por defecto; OpenVoice, SpeechSwift/CosyVoice y Supertonic opcionales. |
+| Discord | Bot token, Message Content intent, voice permissions y channel names coincidentes. |
+| Agent | Al menos un CLI harness autenticado; Hermes Agent por defecto. |
+
+## Nota Docker / contenedores
+
+Si los logs muestran `Cannot perform IP discovery - socket closed`, Discord voice UDP está bloqueado. En Linux Docker Compose usa:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+No combines `network_mode: "host"` con `ports:`.
+
+## Contribuir
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## Estado
+
+VerbalCoding apunta a publicación pública, pero todavía es temprano. Demo video/GIF, validación Linux más amplia, CI y revisión de seguridad siguen como TODO.

package/README.fr.md

@@ -0,0 +1,134 @@
+# VerbalCoding
+
+<p align="center"><strong>Parlez à des agents de code CLI depuis Discord vocal, comme lors d’un appel.</strong></p>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.zh.md">中文</a> · <a href="./README.es.md">Español</a> · <a href="./README.ru.md">Русский</a></p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## Pourquoi ce projet existe
+
+VerbalCoding transforme un salon vocal Discord en poste de pilotage mains libres pour agents de code. Dictez une demande, laissez le CLI travailler, puis recevez une réponse vocale concise avec transcription et progression. Les diffs et logs ne sont pas lus longuement par TTS.
+
+> **Vous utilisez déjà Hermes Agent ?** Hermes prend déjà en charge les salons vocaux Discord via `/voice join` / `/voice channel` : il peut rejoindre votre VC, transcrire avec Whisper et répondre en TTS. Pour cette boucle de base, VerbalCoding n’est pas obligatoire. VerbalCoding ajoute une couche de workflow : routage projet/session, contexte voix+texte partagé, règles d’interruption, annonces de progression, préréglages de langue, métriques de latence et changement de backend CLI au-delà de Hermes.
+
+## Ce qui change
+
+| Capacité | Pourquoi c’est utile |
+|---|---|
+| Flux type appel | Parler, écouter, interrompre et continuer dans le même salon vocal Discord. |
+| Configuration guidée | `vc setup` couvre prerequisites, Discord token/client ID, voice channel, transcript target, backend et TTS settings en un seul flux. |
+| Boucle vocale locale | Discord audio → local `whisper-cli` → selected CLI agent → TTS reply. |
+| Choix de l’agent | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Aider, Cursor CLI ou custom command. `vc setup` détecte automatiquement ce qui est installé. |
+| Routage d’agent par voix | `"ask Codex what it thinks"` pour un tour, `"switch to Aider"` en sticky, `"back to default"` pour revenir. Les binaires absents sont détectés et le pont propose un fallback vers l’agent par défaut. |
+| Au-delà de la voix intégrée de Hermes | Garde la même boucle vocale VC, puis ajoute salons de projet, contexte partagé `!ask`, interruptions réglées, annonces progression/état et contrôle de backends multiagents. |
+| Exploitation réelle | doctor auto-fix, guide Docker UDP, latency metrics, multi-instance rooms et redacted config checks inclus. |
+
+## Démarrage rapide
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+`vc setup` est le parcours normal pour une personne. Gardez Discord Developer Portal ouvert pendant la saisie du bot token, application/client ID, transcript target et voice channel names.
+
+En automatisation, vous pouvez ignorer les prompts puis renseigner Discord ensuite.
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## Discord en une minute
+
+1. Créez une application et un bot dans Discord Developer Portal.
+2. Activez Message Content privileged intent.
+3. Lancez `vc setup` et collez bot token et application/client ID.
+4. Saisissez les noms exacts des voice channels à rejoindre.
+5. Invitez le bot avec ces commandes.
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## Carte rapide des commandes
+
+```bash
+vc setup                                 # configuration guidée: prerequisites, Discord, backend, voice
+vc setup --yes                           # bootstrap/starter config non interactive
+vc setup token                           # modifier ou ajouter Discord bot token/client ID plus tard
+vc setup channels "General,Team Voice"   # mettre à jour auto-join voice channel names
+vc bot invite CLIENT_ID                  # générer Discord bot invite URL
+vc status                                # afficher les réglages actuels
+vc language ko|en|auto                   # changer language preset
+vc doctor                                # redacted health check et auto-fixes
+vc start                                 # démarrer le bridge par défaut
+vc instance setup NAME                   # créer un project voice bot isolé
+vc instance start NAME                   # exécuter ce bot en background
+```
+
+## En savoir plus
+
+| Guide | Contenu |
+|---|---|
+| [Centre de documentation](docs/i18n/README.fr.md) | Index des guides localisés. |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.fr.md) | npm/global setup, configuration Discord, premier lancement. |
+| [Usage](docs/i18n/USAGE.fr.md) | Commandes CLI, commandes Discord, modes d’exécution, latency. |
+| [Usage par harness](docs/i18n/HARNESSES.fr.md) | Installation, configuration et routage vocal pour Claude Code, Codex, Aider et les autres. |
+| [Voix intégrée Hermes vs VerbalCoding](docs/i18n/HERMES_VOICE.fr.md) | La voix Discord déjà fournie par Hermes et la différence VerbalCoding. |
+| [Configuration](docs/i18n/CONFIGURATION.fr.md) | .env, agent backends, MCP, TTS, exploitation. |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.fr.md) | Docker UDP et vérifications token/channel. |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.fr.md) | Un salon vocal fixe par projet. |
+
+## Exigences
+
+| Couche | Défaut |
+|---|---|
+| Runtime | Node.js 20+ et npm. |
+| Audio | `ffmpeg` et local `whisper-cli`. |
+| TTS | Edge TTS par défaut; OpenVoice, SpeechSwift/CosyVoice et Supertonic en option. |
+| Discord | Bot token, Message Content intent, voice permissions et channel names correspondants. |
+| Agent | Au moins un CLI harness authentifié; Hermes Agent par défaut. |
+
+## Note Docker / conteneurs
+
+Si les logs affichent `Cannot perform IP discovery - socket closed`, Discord voice UDP est bloqué. Avec Linux Docker Compose, utilisez:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+Ne combinez pas `network_mode: "host"` avec `ports:`.
+
+## Contribuer
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## Statut
+
+VerbalCoding vise une publication publique mais reste jeune. Vidéo/GIF de démo, validation Linux plus large, CI et revue sécurité restent TODO.

package/README.ja.md

@@ -0,0 +1,134 @@
+# VerbalCoding
+
+<p align="center"><strong>Discord 音声で CLI コーディングエージェントと電話のように作業できます。</strong></p>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh.md">中文</a> · <a href="./README.es.md">Español</a> · <a href="./README.fr.md">Français</a> · <a href="./README.ru.md">Русский</a></p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/verbalcoding?color=CB3837&logo=npm&logoColor=white">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
+  <img alt="Discord" src="https://img.shields.io/badge/Discord-voice%20bridge-5865F2?logo=discord&logoColor=white">
+  <img alt="STT" src="https://img.shields.io/badge/STT-whisper.cpp-7C3AED">
+  <img alt="TTS" src="https://img.shields.io/badge/TTS-Edge%20%7C%20OpenVoice%20%7C%20SpeechSwift-0EA5E9">
+  <img alt="License" src="https://img.shields.io/github/license/ca1773130n/VerbalCoding">
+</p>
+
+<p align="center">
+  <img src="docs/assets/figures/verbalcoding-flow.svg" alt="VerbalCoding voice-to-agent flow" width="860">
+</p>
+
+## なぜ作ったのか
+
+VerbalCoding は Discord の音声ルームを、コーディングエージェント用のハンズフリー操作席に変えます。声で依頼し、CLI エージェントに作業させ、短い音声回答とテキスト記録を受け取れます。diff やログを長々と読み上げないための保護も入っています。
+
+> **すでに Hermes Agent を使っていますか？** Hermes 自体にも `/voice join` / `/voice channel` による Discord 音声チャンネル対応があります。現在の VC に参加し、Whisper STT で文字起こしし、TTS で話し返せます。その基本ループだけなら VerbalCoding は必須ではありません。VerbalCoding はその上に、プロジェクト/セッションルーティング、音声+テキスト共有コンテキスト、割り込みルール、進捗音声、言語プリセット、レイテンシ指標、Hermes 以外の CLI バックエンド切り替えを加えるワークフローレイヤーです。
+
+## 体験の違い
+
+| 機能 | 価値 |
+|---|---|
+| 電話のような流れ | 同じ Discord 音声チャンネルで話す、聞く、割り込む、続けるができます。 |
+| 人向けのガイド付き設定 | `vc setup` が prerequisites、Discord token/client ID、voice channel、transcript target、backend、TTS 設定を一連の流れで確認します。 |
+| ローカル音声ループ | Discord audio → local `whisper-cli` → selected CLI agent → TTS response。 |
+| エージェント選択 | Hermes Agent、Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Aider、Cursor CLI または custom command に対応します。`vc setup` がインストール済みのものを自動検出します。 |
+| 音声でエージェントを切替 | `"ask Codex what it thinks"` で 1 ターンのみ、`"switch to Aider"` で sticky、`"back to default"` で復帰。未インストールのバイナリを検出して既定エージェントへの fallback を提案します。 |
+| Hermes 標準音声の先 | 同じ VC 音声ループを土台に、プロジェクトルーム、`!ask` 共有コンテキスト、細かな割り込み処理、進捗/状態の音声案内、複数エージェントバックエンド制御を追加します。 |
+| 運用向け機能 | doctor auto-fix、Docker UDP ガイド、latency metrics、multi-instance rooms、redacted config checks を備えています。 |
+
+## クイックスタート
+
+```bash
+npm install -g verbalcoding@latest
+vc setup
+vc doctor
+vc start
+```
+
+通常の人間向け導線は `vc setup` です。Discord Developer Portal を開いたまま、bot token、application/client ID、transcript target、voice channel names を入力してください。
+
+自動化ではプロンプトを省略し、Discord の値を後から設定できます。
+
+```bash
+vc setup --yes
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "General,Team Voice"
+vc doctor
+```
+
+## Discord 設定を 1 分で
+
+1. Discord Developer Portal で application と bot を作成します。
+2. Message Content privileged intent を有効にします。
+3. `vc setup` を実行し、bot token と application/client ID を貼り付けます。
+4. 自動参加する voice channel 名を正確に入力します。
+5. 次のコマンドで bot を招待します。
+
+```bash
+vc bot invite <discord-client-id>
+vc bot invite <discord-client-id> --guild <guild-id>
+```
+
+## 小さなコマンド表
+
+```bash
+vc setup                                 # ガイド付き設定: prerequisites, Discord, backend, voice
+vc setup --yes                           # 非対話 bootstrap/starter config
+vc setup token                           # Discord bot token と client ID を後で更新/追加
+vc setup channels "General,Team Voice"   # auto-join voice channel names を更新
+vc bot invite CLIENT_ID                  # Discord bot invite URL を生成
+vc status                                # 現在の設定を表示
+vc language ko|en|auto                   # language preset を切り替え
+vc doctor                                # redacted health check と auto-fix
+vc start                                 # 既定 bridge を開始
+vc instance setup NAME                   # 分離された project voice bot を作成
+vc instance start NAME                   # その bot を background で実行
+```
+
+## 詳しく見る
+
+| ガイド | 得られる内容 |
+|---|---|
+| [ドキュメントハブ](docs/i18n/README.ja.md) | ローカライズ済みガイドの索引。 |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.ja.md) | npm/global setup、Discord 設定、初回起動。 |
+| [Usage](docs/i18n/USAGE.ja.md) | CLI コマンド、Discord コマンド、実行モード、latency。 |
+| [Harness 別の使い方](docs/i18n/HARNESSES.ja.md) | Claude Code、Codex、Aider などバックエンド別のインストール・設定・音声ルーティング。 |
+| [Hermes 標準音声 vs VerbalCoding](docs/i18n/HERMES_VOICE.ja.md) | Hermes がすでに提供する Discord 音声と VerbalCoding の違い。 |
+| [Configuration](docs/i18n/CONFIGURATION.ja.md) | .env、agent backends、MCP、TTS、運用。 |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.ja.md) | Docker UDP、token/channel 不足チェック。 |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.ja.md) | プロジェクトごとに固定音声ルームを 1 つ。 |
+
+## 要件
+
+| レイヤー | 既定 |
+|---|---|
+| Runtime | Node.js 20+ と npm。 |
+| Audio | `ffmpeg` と local `whisper-cli`。 |
+| TTS | 既定は Edge TTS。OpenVoice、SpeechSwift/CosyVoice、Supertonic は任意。 |
+| Discord | Bot token、Message Content intent、voice permissions、一致する channel names。 |
+| Agent | 認証済み CLI harness が 1 つ以上。既定は Hermes Agent。 |
+
+## Docker / コンテナ注意
+
+ログに `Cannot perform IP discovery - socket closed` が出る場合、Discord voice UDP がブロックされています。Linux Docker Compose では次を使います:
+
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
+```
+
+`network_mode: "host"` と `ports:` を併用しないでください。
+
+## コントリビューション
+
+```bash
+node --check app-node/main.mjs
+npm test
+bash -n run.sh scripts/install.sh scripts/bootstrap_prereqs.sh
+npm pack --dry-run
+vc doctor
+```
+
+## 状態
+
+VerbalCoding は公開リリースを目指していますが、まだ初期段階です。デモ動画/GIF、より広い Linux 検証、CI、セキュリティレビューは TODO です。