{"id":48717736,"url":"https://github.com/celanthe/clarion","last_synced_at":"2026-04-11T18:01:50.497Z","repository":{"id":342849998,"uuid":"1173778014","full_name":"celanthe/clarion","owner":"celanthe","description":"Your agents have things to say. Now they have a voice to say them with.","archived":false,"fork":false,"pushed_at":"2026-04-04T18:50:18.000Z","size":963,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T21:23:13.699Z","etag":null,"topics":["agent","agent-framework","agentic","agentic-ai","agentic-workflow","agents","claude","claude-ai","claude-code","claude-code-plugin","edge-tts","kokoro-tts","piper-tts","text-to-speech","tts","voice-assistant"],"latest_commit_sha":null,"homepage":"https://kiranoliver.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/celanthe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":null}},"created_at":"2026-03-05T18:35:02.000Z","updated_at":"2026-04-04T18:50:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/celanthe/clarion","commit_stats":null,"previous_names":["celanthe/clarion"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/celanthe/clarion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celanthe%2Fclarion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celanthe%2Fclarion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celanthe%2Fclarion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celanthe%2Fclarion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/celanthe","download_url":"https://codeload.github.com/celanthe/clarion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celanthe%2Fclarion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31689762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-framework","agentic","agentic-ai","agentic-workflow","agents","claude","claude-ai","claude-code","claude-code-plugin","edge-tts","kokoro-tts","piper-tts","text-to-speech","tts","voice-assistant"],"created_at":"2026-04-11T18:00:57.605Z","updated_at":"2026-04-11T18:01:50.492Z","avatar_url":"https://github.com/celanthe.png","language":"JavaScript","funding_links":["https://ko-fi.com/rinoliver"],"categories":[],"sub_categories":[],"readme":"# Clarion\n\n**Give your AI agent a voice.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/celanthe/clarion)](https://github.com/celanthe/clarion/stargazers)\n[![Last commit](https://img.shields.io/github/last-commit/celanthe/clarion)](https://github.com/celanthe/clarion/commits/main)\n[![Version](https://img.shields.io/badge/version-0.7.0-green)](https://github.com/celanthe/clarion)\n\nSelf-hosted TTS proxy and voice manager. Audition voices against your agent's actual dialogue, pick one, and pipe responses through it from the browser or CLI.\n\n\u003e Voice starts while your agent is still working. `clarion-watch` speaks each assistant message the moment it's written — even before tool calls finish.\n\n![Clarion waveform visualization showing audio output from the voice audition interface](docs/img/clarion-waveform.png)\n\n---\n\n## What it does\n\n- **Live session voice.** `clarion-watch` speaks each assistant message as soon as it is written — including text before tool use. Voice starts while Claude is still working.\n- **Audition voices.** Paste your agent's characteristic dialogue. Hear each voice read it. Pick the one that fits.\n- **Save agent profiles.** One agent uses Kokoro `bm_george` at 1.0x, another uses Edge `en-GB-SoniaNeural`. Both saved, both exportable as JSON.\n- **Six TTS backends.** Edge TTS (zero config), Kokoro (self-hosted, natural), Chatterbox (self-hosted, ElevenLabs-quality), Piper (self-hosted, lightweight), ElevenLabs (paid), Google Chirp 3 HD (paid).\n- **Terminal integration.** Pipe agent responses through their voice from the CLI. Works with Claude Code via `clarion-watch` (live daemon) or the stop hook.\n- **Multi-agent support.** Running several agents at once? Concurrent responses queue automatically and speak in the order they finished — no overlapping audio.\n\n---\n\n## Quickstart\n\nRequires Node.js 18+ and npm. Start with UI only — it works out of the box. Add the server later if you want higher-quality voices.\n\n### UI only (Edge TTS, no setup needed)\n\n```sh\nnpm install\nnpm run dev\n# http://localhost:5173\n```\n\n### With server (required for Kokoro, Piper, ElevenLabs, Google)\n\nRun in a second terminal alongside the UI:\n\n```sh\ncd server \u0026\u0026 npm install \u0026\u0026 npm run dev\n# http://localhost:8080\n```\n\nOr with Docker (Kokoro included):\n\n```sh\ndocker compose up\n# Kokoro at :8880, Clarion server at :8080\n```\n\n---\n\n## Why Clarion?\n\nMost TTS tools give you an API. Clarion gives you a workflow.\n\n- **Audition, don't guess** — hear each voice read your agent's actual dialogue before you commit\n- **Self-hosted** — your audio, your servers, your data\n- **proseOnly** — strips code blocks, markdown, and structure so agents speak naturally, not robotically\n- **Live voice** — `clarion-watch` speaks during the session, not after\n- **Six backends** — swap from free (Edge) to premium (ElevenLabs) without changing a line of agent code\n- **Multi-agent crews** — each agent gets its own voice, concurrent responses queue automatically\n\n---\n\n## Architecture\n\n![Clarion architecture — Browser UI and CLI tools connect through the services layer to the Clarion server, which routes to six TTS backends](docs/img/clarion-architecture.svg)\n\nSix layers: **UI** (React SPA), **Services** (TTS client, HMAC crypto, localStorage), **Server** (Hono on Cloudflare Workers or Node), **Domain** (agent model, voice lists), **CLI** (watch, speak, stream, doctor), and **Design System** (CSS tokens). The server proxies to six TTS backends — Edge TTS is always available as a zero-config fallback.\n\n---\n\n## Voice audition\n\n1. Open the **Audition** tab\n2. Paste your agent's characteristic dialogue\n3. Select a backend (Kokoro for the most natural voices)\n4. Click play next to a voice to hear it read your text\n5. Click **Use this voice**, name the agent, done\n\nShort, characteristic sentences work best. Paste what your agent would actually say, not generic test text.\n\n---\n\n## CLI\n\n```sh\n# Install globally (run once from the Clarion directory)\nnpm install -g .\n\n# Set up your first agent (interactive — picks a voice, writes the hook)\nclarion-init\n\n# Speak as a saved agent\necho \"The pattern holds.\" | clarion-speak --agent my-agent\n\n# Stream in real time, sentence by sentence\nclaude \"Walk me through this.\" | clarion-stream --agent my-agent\n\n# Watch a Claude Code session live — speaks mid-session, before tools finish\nclarion-watch --agent my-agent\n\n# Multi-agent mode — one router watches all projects, routes each to the right voice\nclarion-watch --multi\n\n# Migrate voice configs from Terminus to Clarion\nclarion-migrate --dry-run\n\n# Diagnose setup issues — 10 checks with remediation hints\nclarion-doctor\n\n# Check server health, loaded agents, and playback status\nclarion-status\n\n# Mute an agent\nclarion-mute my-agent\nclarion-mute my-agent --off\n```\n\n[Full CLI guide](docs/cli.md): `clarion-doctor`, `clarion-init`, `clarion-speak`, `clarion-stream`, `clarion-watch`, `clarion-router`, `clarion-migrate`, `clarion-status`, `clarion-mute`, `clarion-log`, and the Claude Code stop hook.\n\n---\n\n## API\n\n```\nPOST /speak\nBody: { \"text\": \"Hello.\", \"backend\": \"edge\", \"voice\": \"en-GB-RyanNeural\", \"speed\": 1.0 }\nReturns: audio/mpeg (X-Clarion-Fallback header if backend fell back to Edge)\n\nGET /voices?backend=edge|kokoro|piper|elevenlabs|google|chatterbox\nReturns: { voices: [{ id, label, lang, gender }] }\n\nGET /health\nReturns: { edge: \"up\", kokoro: \"up|down|unconfigured\", ... }\n\nGET /diagnostics\nReturns: { server: { version }, backends: { [name]: { status, configured, detail } } }\n```\n\n---\n\n## Backends\n\n| Backend | Config needed | Quality | Voices |\n|---------|--------------|---------|--------|\n| Edge TTS | None* | Good | 27 Neural (US, UK, AU, IE, CA, ZA, NZ, IN) |\n| Kokoro | `KOKORO_SERVER=http://...` | Excellent | 11 (US + UK English) |\n| Chatterbox | `CHATTERBOX_SERVER=http://...` | Excellent | Voice cloning — unlimited (requires GPU) |\n| Piper | `PIPER_SERVER=http://...` | OK | 6 (US + UK English) |\n| ElevenLabs | `ELEVENLABS_API_KEY=...` | Excellent | 11 (US, UK, AU) |\n| Google Chirp 3 HD | `GOOGLE_TTS_API_KEY=...` | Excellent | 16 (US + UK) |\n\n\\*Edge TTS uses Microsoft's public Translator API. No API key is required, but this is an unofficial integration and availability is not guaranteed.\n\n[Backend setup guide](docs/backends.md): local Kokoro and Piper install, Docker, API key setup.\n\n---\n\n## What gets spoken\n\nBy default (`proseOnly: true`), Clarion strips non-conversational markdown before sending text to the TTS backend — so your agent only speaks what it would actually say, not the structure around it.\n\n| Content | Spoken? |\n|---|---|\n| Prose paragraphs | Yes |\n| Heading text (`## Like this`) | Yes — markers stripped |\n| Bold / italic / strikethrough | Yes — markers stripped |\n| Links (`[text](url)`) | Yes — link text spoken |\n| Images (`![alt](url)`) | Yes — alt text spoken |\n| Blockquotes (`\u003e text`) | Yes — markers stripped |\n| Bullet lists (`- item`) | Yes — markers stripped |\n| Numbered lists (`1. item`) | Yes — markers stripped |\n| Fenced code blocks (` ``` `) | No — removed |\n| Inline code (`` `like this` ``) | No — removed |\n| Indented code blocks | No — removed |\n| HTML tags | No — removed |\n| Horizontal rules (`---`) | No — removed |\n\nToggle **Prose only** off on any agent card if you want everything spoken verbatim — useful for agents that narrate code reviews or read structured output.\n\n---\n\n## Agent profiles\n\nProfiles are stored in `localStorage` and exportable as JSON.\n\n```json\n{\n  \"id\": \"my-agent\",\n  \"name\": \"My Agent\",\n  \"backend\": \"kokoro\",\n  \"voice\": \"bm_george\",\n  \"speed\": 1.0,\n  \"proseOnly\": true\n}\n```\n\nExport from the UI (Export all button) or share a single agent profile as a `.json` file. Import via the Import button.\n\n---\n\n## Deploy\n\n**Cloudflare Worker** (Edge TTS only, or with secrets for paid backends):\n\n```sh\ncd server \u0026\u0026 wrangler deploy\nwrangler secret put KOKORO_SERVER\nwrangler secret put ELEVENLABS_API_KEY\nwrangler secret put GOOGLE_TTS_API_KEY\n```\n\n**Docker Compose** (for local Kokoro):\n\n```sh\ndocker-compose up\n```\n\n**Chatterbox on RunPod** (or any NVIDIA GPU server):\n\nSee [docs/chatterbox.md](docs/chatterbox.md) for the full setup guide.\n\n---\n\n## Troubleshooting\n\n**No audio output?**\nEdge TTS returns `audio/mpeg`. Make sure your player supports it. From CLI, Clarion auto-detects `afplay` (macOS), `mpv`, `ffplay`, `paplay`, or `cvlc` (Linux). On Windows, `mpv`, `ffplay`, or `vlc` are detected. Pass `--player \u003ccommand\u003e` to override.\n\n**Kokoro connection refused?**\nCheck `KOKORO_SERVER` is set and the server is running on the right port. Docker: `docker-compose up` handles this automatically. Verify with `clarion-status`.\n\n**`clarion-watch` not speaking?**\nRun `clarion-log` to check recent entries. Make sure the agent profile exists: `clarion-speak --list-agents`. Check mute state: `clarion-mute --list`.\n\n**Audio overlapping between agents?**\n`clarion-stream` uses a process lock file to serialize playback. If a stale lock remains after a crash, delete `$TMPDIR/clarion-stream.lock`.\n\n---\n\n## Security\n\nClarion is designed for personal, self-hosted use. For deployments beyond localhost:\n\n- Set `API_KEY=your-secret` in the server environment. The browser UI signs requests with HMAC-SHA256. The CLI uses `Bearer \u003ckey\u003e`. Use HTTPS for remote deployments.\n- CORS is open (`*`) by default. Set `ALLOWED_ORIGIN=https://your-domain.com` to restrict it.\n- `kokoro-server.py` and `piper-server.py` bind to `127.0.0.1` by default. Do not expose them on `0.0.0.0` unless you trust the network.\n\n---\n\n## Privacy\n\nClarion sends the text you provide to whichever TTS backend is selected. **Edge TTS, ElevenLabs, and Google Chirp 3 HD** route text through external APIs (Microsoft, ElevenLabs, and Google respectively). **Kokoro, Chatterbox, and Piper** are fully self-hosted — text never leaves your infrastructure. Choose your backend accordingly. No text is stored by the Clarion server.\n\n---\n\n## Ecosystem\n\nClarion is part of the [zerovector.design](https://zerovector.design) ecosystem — tools for building directly from intent to artifact. See also [Terminus](https://github.com/celanthe/terminus), the zero-overhead orchestration layer for multi-agent workflows.\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, code style, and how to add a backend.\n\nClarion is an audio tool, but contributions are not limited to people who use audio. UI improvements, backend adapters, documentation, and testing are all valuable.\n\n---\n\n## Credits\n\nBuilt by [celanthe](https://github.com/celanthe) · Design by [Zabethy](https://zabethy.com) · Inspired by [Investiture](https://zerovector.design/investiture) by [Erika Flowers](https://github.com/erikaflowers) and [Everbloom Reader](https://everbloomreader.com)\n\n[![Support Clarion on Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/rinoliver)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelanthe%2Fclarion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelanthe%2Fclarion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelanthe%2Fclarion/lists"}