{"id":51689002,"url":"https://github.com/5uck1ess/cicero","last_synced_at":"2026-07-16T00:05:08.175Z","repository":{"id":371186849,"uuid":"1299715232","full_name":"5uck1ess/cicero","owner":"5uck1ess","description":"Self-hosted voice for coding agents. Talk from any browser or a Telegram call, interrupt mid-sentence, clone any voice, and hand real work to agents that ship PRs. Local STT/TTS; real-time voice client for ACP.","archived":false,"fork":false,"pushed_at":"2026-07-13T20:58:28.000Z","size":1272,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-13T22:22:46.169Z","etag":null,"topics":["agent-client-protocol","bun","claude-code","coding-agent","local-first","ollama","self-hosted","speech-synthesis","telegram","tts","typescript","voice-assistant","voice-cloning","voice-interface"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5uck1ess.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-07-13T20:37:25.000Z","updated_at":"2026-07-13T20:58:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/5uck1ess/cicero","commit_stats":null,"previous_names":["5uck1ess/cicero"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/5uck1ess/cicero","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5uck1ess%2Fcicero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5uck1ess%2Fcicero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5uck1ess%2Fcicero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5uck1ess%2Fcicero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5uck1ess","download_url":"https://codeload.github.com/5uck1ess/cicero/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5uck1ess%2Fcicero/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35524901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-client-protocol","bun","claude-code","coding-agent","local-first","ollama","self-hosted","speech-synthesis","telegram","tts","typescript","voice-assistant","voice-cloning","voice-interface"],"created_at":"2026-07-16T00:05:07.353Z","updated_at":"2026-07-16T00:05:08.166Z","avatar_url":"https://github.com/5uck1ess.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo-light.svg\"\u003e\n    \u003cimg alt=\"Cicero\" src=\"assets/logo-dark.svg\" width=\"520\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n**Cicero is a self-hosted voice interface for coding agents: you speak, it answers out loud, and your agent does the actual work.** Install it next to the agent you already use — Claude Code, Codex, Gemini, an [ACP](https://agentclientprotocol.com) harness like [hermes](https://hermes-agent.nousresearch.com), or any OpenAI-compatible endpoint — then talk to that agent from any browser on your network — or, with the optional Telegram sidecar, over a real phone call. Say *\"fix the failing auth test and open a PR\"*; Cicero acknowledges in about a second, the work happens in the background (commands you've gated, like a `git push`, need your spoken yes), and it tells you when the PR is up. With local providers, your audio never leaves your machine.\n\n**Local voice in, pull requests out.** In more detail:\n\n- **~1 second to first spoken word** (on a local NVIDIA GPU) — local [faster-whisper](https://github.com/SYSTRAN/faster-whisper) speech recognition, sentence-streamed speech synthesis, latency-covering filler clips. Measured end-to-end through a real tool-calling agent, not a parrot.\n- **Any voice, cloned locally** — zero-shot cloning from a single reference WAV, down to **36–46 ms per sentence** ([audio.cpp](https://github.com/0xShug0/audio.cpp) pocket-tts, ggml/CUDA). Hand it a clip; that's Cicero's voice now.\n- **Interrupt it mid-sentence** (\"barge-in\") — talk over Cicero on the browser and phone paths (and on the local mic when you enable full-duplex) and speech stops while cancellable brain adapters receive the interrupt; terminal-UI injection translates it to a bounded, best-effort terminal control. Only *speech* interrupts: a small local VAD model confirms a human is talking before anything cuts Cicero off, so keyboard clatter and background music don't — and with hands-free auto-start, the dormant page itself wakes when you speak. (Honest label: turn-taking with fast interruption — not a speech-to-speech model that comprehends while talking.)\n- **Knows when you're done talking** — opt-in semantic end-of-turn detection ([Smart-Turn](docs/turn-detection.md), the same approach ChatGPT and Gemini voice use, here fully local): a tiny model (~8 M params, ~12 ms on CPU) reads the prosody and completeness of what you said instead of just timing the pause — so it can answer as soon as your sentence is complete instead of waiting out a silence timer, and keeps the mic open when you trail off mid-thought. Works on the browser path and the local mic; one `turn:` block in the config enables it.\n- **Hears *how* you said it** — an optional speech-emotion sidecar ([emotion2vec](https://github.com/ddlBoJack/emotion2vec), CPU-only) classifies your tone in parallel with transcription and passes a confident non-neutral read to the agent — it knows the difference between \"great\" and *\"great.\"* — at ~0 ms added latency, fully local.\n- **A whole office behind one call** — lanes give you a team of agents, each with its own voice and personality: *\"let me talk to the coder\"* transfers the call, *\"roll call\"* makes everyone check in. Cicero speaks up on its own too: task finished, morning briefing, quiet hours respected.\n- **Agent-agnostic by design** — the brain is a pluggable slot. Cicero owns the voice; your agent owns the doing.\n\n---\n\n## Words we use\n\nSix terms cover most of the docs:\n\n| Term | Meaning |\n|---|---|\n| **brain** | The coding agent that does the thinking — Claude Code, Codex, Gemini, an ACP harness. Cicero is the voice wrapped around it, and ships no brain of its own. |\n| **barge-in** | Talking over Cicero. It stops speaking and listens. |\n| **lane** | One brain + voice + personality. |\n| **the office** | Several lanes behind one call: *\"let me talk to the coder\"* transfers you, *\"back to Cicero\"* returns. |\n| **sidecar mode** | The lightweight mode: Cicero attaches to an agent session you already run and speaks its replies. No models, no config. |\n| **daemon mode** | The full product: browser / phone / local mic in, a brain in the middle, a cloned voice out. |\n\n\u003e **Project status:** Active development. Web-voice, daemon, and sidecar modes work today; the [evaluation follow-up](docs/evaluation-follow-up-2026-07.md) records current limits. Files under `docs/superpowers/plans/` and `docs/superpowers/specs/` are historical design records, not the current backlog.\n\n## How a turn flows\n\n```mermaid\nflowchart LR\n    Y((you)) --\u003e|speech| B[\"browser / PWA\u003cbr/\u003eor Telegram call\"]\n    B --\u003e|audio| S[\"STT\u003cbr/\u003efaster-whisper · local\"]\n    S --\u003e|text| SW{\"switchboard\u003cbr/\u003etransfers · quick intents\"}\n    SW --\u003e|turn| BR[\"brain lane\u003cbr/\u003eany ACP agent\"]\n    BR --\u003e|sentences| T[\"TTS · cloned voice\u003cbr/\u003eper-lane · local\"]\n    T --\u003e|audio| B\n    BR -.-\u003e|files tasks| K[\"kanban → async workers → PR\"]\n    K -.-\u003e|done| N[\"notify: speaks up,\u003cbr/\u003etexts, or rings you\"]\n```\n\nReplies stream sentence-by-sentence, so speech starts while the brain is still generating. Heavy work runs *outside* the voice loop: the agent files it on its board, workers build and open the PR async, and Cicero tells you when it lands. Details in [architecture](docs/architecture.md).\n\n---\n\n## What you'll need\n\n- **An OS.** Linux is the reference setup, with an NVIDIA GPU (CUDA) or plain CPU; macOS 14+ on Apple Silicon and Windows (CUDA) are supported — see [setup](docs/setup.md) for those paths.\n- **A GPU is recommended, not required.** The latency numbers above come from an NVIDIA card. On Linux, everything also runs on CPU: transcription gets noticeably slower, but the default voice engine (pocket-tts) is CPU-friendly at roughly half a second per sentence. On Apple Silicon (measured on an M4), the local MLX stack transcribes a spoken command in about a second and pocket-tts runs ~0.4 s per sentence (≈9× realtime) — see [stored results](docs/performance-portability-evaluation.md#stored-results--apple-silicon-m4) for the measured numbers.\n- **Disk and patience for first start.** The speech models and the small local LLM download on first use — expect a few GB.\n- **Tools:** [Bun](https://bun.sh) (the runtime), [uv](https://docs.astral.sh/uv/) (manages the Python model servers), ffmpeg, [Ollama](https://ollama.com) (runs the small local router model), and OpenSSL (used once, to create the HTTPS certificate).\n- **A coding agent, installed and authenticated.** Cicero ships no brain — bring Claude Code, Codex, Gemini, or any ACP/OpenAI-compatible harness.\n\n## Try it in two minutes (sidecar mode)\n\nThe zero-commitment path — no GPU, no model downloads, no config file. If you already use Claude Code or Codex, clone this repository, `cd` into it, and run:\n\n```bash\nbun install \u0026\u0026 bun link                 # expose the `cicero` CLI from this checkout\nsudo apt install speech-dispatcher      # Linux only: the system voice (macOS has `say` built in)\ncicero hook install claude-code         # or: cicero hook install codex\ncicero hook                             # leave running in a second terminal\n```\n\nEvery hooked session now speaks its responses out loud — in your plain system voice until you add a real TTS engine, and the response's last line until you point Cicero at a local LLM for summaries. Codex asks you to trust a newly installed command hook in `/hooks`; terminal-scrape mode remains available for Gemini and agents without native hooks. Details are in [setup → sidecar quickstart](docs/setup.md#sidecar-quickstart-claude-code-and-codex).\n\n## The full setup (web voice)\n\nThe flagship shape: Cicero on a Linux box (GPU or not), you talking to it from any browser on your network.\n\n**1. Install the prerequisites** (skip any you have):\n\n```bash\ncurl -fsSL https://bun.sh/install | bash            # Bun\ncurl -LsSf https://astral.sh/uv/install.sh | sh     # uv\nsudo apt install ffmpeg openssl                     # Debian/Ubuntu (brew/scoop elsewhere)\ncurl -fsSL https://ollama.com/install.sh | sh       # Ollama (other platforms: https://ollama.com/download)\n```\n\n**2. Get Cicero and its speech servers.** Clone this repository, `cd` into it, and run everything below from that checkout (the daemon launches and supervises the model servers itself):\n\n```bash\nbun install\nbun link                    # expose the `cicero` CLI from this checkout\n\nuv venv .venv-stt --python 3.10\nuv pip install --python .venv-stt -r requirements/faster-whisper.txt\nuv venv .venv-pocket --python 3.11\nuv pip install --python .venv-pocket -r requirements/pocket-tts.txt\nollama pull qwen3.5:4b\n```\n\n**3. Create the config.** Make `~/.cicero/config.yaml` with exactly this content (don't copy `config.yaml.example` for a first run — it documents every option and expects backends this quickstart doesn't install):\n\n```yaml\n# ~/.cicero/config.yaml — the minimal web-voice setup\nheadless: true\nweb_voice: { enabled: true, host: 0.0.0.0, port: 8090 } # a fresh token prints at startup\nstt: { backend: faster-whisper, port: 8083, model: large-v3-turbo }\ntts: { backend: pocket-tts, port: 8095, voice: alba }\nllm: { backend: ollama, port: 11434, model: qwen3.5:4b }\nbrain: { backend: claude-code, mode: subprocess } # or acp / codex / gemini / ollama / any OpenAI-compatible URL\n```\n\n**4. Pick your brain.** The config above expects the Claude Code CLI — install it and log in before continuing. For Hermes or another ACP harness, set `brain: { backend: acp, binary: …, binary_args: […] }` instead — see [Brains](docs/brains.md).\n\n**5. Check, start, talk:**\n\n```bash\ncicero doctor   # checks configured backends and prints fixes\ncicero start\n# → 🎙️  Web voice server on https://0.0.0.0:8090 (token required)\n```\n\nOpen `https://\u003cbox-ip\u003e:8090/?token=\u003ctoken\u003e`, accept the self-signed certificate once, hold SPACE (or the orb), and talk. Full page controls, hands-free mode, and the PWA install are in the [web-voice guide](docs/web-voice.md); macOS / Windows / systemd / remote-GPU setups in [setup](docs/setup.md).\n\n## When something doesn't work\n\n- **The browser warns about the certificate.** Expected: Cicero generates a self-signed HTTPS certificate on first start (browsers only expose the microphone over HTTPS). Accept it once per device.\n- **Where's the token?** Printed at startup, once per run. For a stable token across restarts, run `openssl rand -hex 16` and paste only its output as `token:` inside the `web_voice:` block (e.g. `web_voice: { enabled: true, host: 0.0.0.0, port: 8090, token: \u003cpaste\u003e }`). Configure it before running Cicero under a service manager, because startup stdout may be retained — and never copy an example placeholder as a secret.\n- **I talk and nothing happens.** The default is push-to-talk: hold SPACE or the orb *while* speaking. Then check the browser's microphone permission, then `cicero doctor`.\n- **`doctor` is green but turns fail.** `doctor` verifies configuration and binaries; it does not prove a CLI login or complete a live agent turn. Make sure the brain's own CLI works standalone, then exercise one real turn.\n- Anything else: `cicero doctor` first — it names the missing prerequisite and the command that fixes it.\n\n---\n\n## What you can do with it\n\n- **Delegate real work by voice** — \"fix the failing auth test and open a PR\" gets acked in a second, built async, and announced when the PR is up. [The office →](docs/office.md)\n- **Talk to a team, not a bot** — per-lane agents with their own memory, voice, and personality; sticky transfers; roll call; standups read from the task board. [Lanes →](docs/office.md)\n- **Clone any voice you're authorized to use** — add one WAV for a supported provider, then `voice use` selects that provider and its safe reference or cloud ID end to end; per-employee voices can mix clones and presets. [Voice cloning →](docs/voice-cloning.md)\n- **Let it reach you** — proactive speech in the browser, Telegram voice notes, or a real phone call; quiet hours queue the news and the morning briefing reads it back — once, at *your* 8:30. Scheduled prompts go the other way: give a lane a prompt and a time in the config and it briefs you daily on whatever you asked. [Notifications →](docs/notifications.md)\n- **Follow up without re-explaining** — every delivered notification is also handed to the brain as context for your next turn: Cicero says a PR got a review comment, you answer *\"take care of it\"*, and the agent knows what *it* refers to. [Notifications →](docs/notifications.md)\n- **Log life in passing** — text the bot `log calories 650` or `log weight 82.4` and it appends to a local health record instantly, no agent turn; `cicero health recent|trend` reads it back, and `POST /api/health` bridges phone automations. [Notifications →](docs/notifications.md)\n- **Summon the call by voice** — say *\"call me\"* (or *\"have Ada call me\"*) on any voice surface and your phone rings via the Telegram sidecar. Intent, not wording: a small local classifier rings on *\"I want you to call me\"* but just answers *\"did you call me?\"*. [Notifications →](docs/notifications.md)\n- **Keep the sharp edges gated** — destructive tool calls are denied fail-closed until you approve them out loud. [Confirmation gate →](docs/brains.md)\n- **Take it off the leash** — `cicero do \"\u003cgoal\u003e\"` runs local tool-use with spoken confirmation on anything mutating. [Computer use →](docs/daemon-mode.md)\n\n---\n\n## How it compares\n\nCicero's differentiator is the combination of local STT, local cloned-voice\nTTS, hot-mic barge-in, semantic turn detection, and delegation to autonomous\ncoding agents:\n\n- **Compared with voice-chat stacks**, Cicero connects the conversation to a\n  tool-using agent so turns can end in work products such as tasks, branches,\n  and PRs.\n- **Compared with agent orchestration tools**, Cicero supplies the capture,\n  interruption, synthesis, and notification layer while leaving the chosen\n  agent in charge of the work.\n- **Compared with cloud realtime speech APIs**, Cicero can keep STT and TTS on\n  hardware you control and treats the brain as a replaceable adapter.\n\nCicero also acts as a real-time voice client for any\n[Agent Client Protocol](https://agentclientprotocol.com)-speaking harness —\na live, interruptible spoken conversation, not transcribed voice messages.\n\n---\n\n## Docs\n\n- [Setup](docs/setup.md) — Linux / macOS / Windows install, sidecar quickstart, remote model servers, systemd, CLI reference\n- [Web-voice mode](docs/web-voice.md) — the browser/PWA experience: controls, hands-free, barge-in, restart resume\n- [The office](docs/office.md) — lanes, transfers, personas, the operator pattern, an example team topology\n- [Brains](docs/brains.md) — every backend, verified ACP harnesses, the spoken confirmation gate, bring-your-own-harness\n- [Notifications](docs/notifications.md) — proactive voice-back, kanban watch, Telegram notes \u0026 calls, quiet hours + briefing\n- [Turn detection](docs/turn-detection.md) — semantic end-of-turn (Smart-Turn): why silence timers cut you off, the model server, tuning\n- [Voice cloning](docs/voice-cloning.md) — the library, engines and latencies, getting a clone to sound right\n- [Daemon mode](docs/daemon-mode.md) — local mic, full-duplex, double-clap, computer use\n- [Configuration](docs/configuration.md) — full config reference, default model stacks, quick intents, custom actions\n- [Architecture](docs/architecture.md) — the turn pipeline, components, where your data lives\n- [Full duplex](docs/duplex.md) — why Cicero takes turns: the fused-vs-modular tradeoff, and what would change the call\n- [Security model](docs/security.md) — the threat model, the token, TLS, what egresses and what never does\n- [Evaluation follow-up](docs/evaluation-follow-up-2026-07.md) — delivered fixes, current limits, and intentional architecture boundaries\n\n---\n\n## Development\n\n```bash\nbun test                  # full test suite\nbun run dev               # dev mode with watch\n```\n\nThe default suite does not contact external agent services, even when `.env`\ncontains credentials. To run the opt-in Claude CLI smoke test, install and\nauthenticate Claude Code, then run:\n\n```bash\nCICERO_LIVE_TESTS=1 bun test tests/brain-claude-code-stream.test.ts\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE). Voice cloning is BYO-voice: Cicero ships no third-party voices, and cloning someone without consent is on you, not the tool — see [authorized use](docs/voice-cloning.md#authorized-use-only).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5uck1ess%2Fcicero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5uck1ess%2Fcicero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5uck1ess%2Fcicero/lists"}