verbalcoding 0.2.10 → 0.2.12

package/.env.example

@@ -1,17 +1,43 @@
 # 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=""
 
-# 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: enables sentence-by-sentence playback while the agent is still writing.
+# First audio plays before the agent finishes. Default off; opt in once you've validated TTS latency.
+STREAMING_TTS="0"
+
+# 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`.

package/README.es.md

@@ -0,0 +1,132 @@
+# 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 o custom command. |
+| 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. |
+| [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,132 @@
+# 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 ou custom command. |
+| 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. |
+| [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,132 @@
+# 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、custom command に対応します。 |
+| 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。 |
+| [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 です。

package/README.ko.md

@@ -0,0 +1,132 @@
+# VerbalCoding
+
+<p align="center"><strong>Discord 음성으로 CLI 코딩 에이전트와 통화하듯 작업하세요.</strong></p>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.ja.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와 로그는 TTS로 길게 읽지 않도록 보호합니다.
+
+> **Hermes Agent를 이미 쓰고 있나요?** Hermes 자체도 `/voice join` / `/voice channel`로 Discord 음성 채널에 들어가 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 답변. |
+| 에이전트 선택 | Hermes Agent, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, custom command를 지원합니다. |
+| 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.ko.md) | 현지화된 가이드 색인. |
+| [Fresh Install](docs/i18n/FRESH_INSTALL.ko.md) | npm/global setup, Discord 설정, 첫 실행. |
+| [Usage](docs/i18n/USAGE.ko.md) | CLI 명령, Discord 명령, 실행 모드, latency. |
+| [Hermes 기본 음성 vs VerbalCoding](docs/i18n/HERMES_VOICE.ko.md) | Hermes가 이미 지원하는 Discord 음성과 VerbalCoding의 차이. |
+| [Configuration](docs/i18n/CONFIGURATION.ko.md) | .env, agent backends, MCP, TTS, 운영. |
+| [Troubleshooting](docs/i18n/TROUBLESHOOTING.ko.md) | Docker UDP, token/channel 누락 점검. |
+| [Multi-Instance](docs/i18n/MULTI_INSTANCE.ko.md) | 프로젝트마다 하나의 고정 음성 방. |
+
+## 요구 사항
+
+| 계층 | 기본값 |
+|---|---|
+| 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 하나 이상, 기본은 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입니다.