sidevoice-connector
Reading your coding agent's plans, diffs and summaries all day is tiring. Sidevoice turns the conversation you already have with your agent into a voice call. The agent keeps its context and keeps writing as usual; it also speaks its replies, and you answer by voice and can interrupt it — from the sofa or on a walk, not only at your desk.
sidevoice-connector is what you install on the machine where your agents run, published on npm as
sidevoice. It gives each agent conversation its voice
tools (an MCP server), delivers what you say into that same conversation, and installs and starts the
machine's core.
How it fits
Your machine is the computer where your coding agents run; a device is what you call from (the desktop app, a browser).
If a reply to the connector's speech request is lost, the connector keeps the original request and asks the core for its disposition with speech.recover after reconnecting. The core returns the original saved or refused result; if it never received the request, it saves the text without playing delayed audio. The connector retains a bounded receipt for the recovered result so an agent retry with the same IDs sees it, even if background recovery finished first. Once that attempt is settled, a new reply in the current conversation can play normally. A queued reply is never retried as new audio when its first admission is uncertain.
Notices delivered through the agent's push or pull mode carry the same confirmed hearing evidence: heard, partially heard with a Unicode-scalar extent, or not heard. The full reply text remains available so the agent knows what was left unheard. A missing receipt stays unconfirmed and does not become a not-heard claim. An already delivered notice keeps its message ID and content across retries; stronger late hearing arrives as a separate reply_heard correction.
Get started
You need macOS on Apple silicon, Linux on x64 or arm64 with glibc, or Windows on x64 (see Status), and Node.js 18 or
newer for npx. The npm package sidevoice is a small launcher: npm installs beside it the connector built for
your machine (@sidevoice/sidevoice-<os>-<cpu>, with the core inside); installing downloads nothing else.
-
Install, on the machine where your agents run:
npx sidevoice installIt installs and starts this machine's core and lists the agents it finds. It connects none of them by itself: run in a terminal, it offers to connect them (none unless you choose); otherwise connect each one you want from the desktop app, or with
npx sidevoice agents connect <claude|codex|cursor>. It tells you what, if anything, needs a manual step (see Supported agents). An agent you connected with an older Sidevoice stays connected.A release candidate, when there is one:
npx sidevoice@next install. -
Pair your device. Ask your agent to pair a device, or run
npx sidevoice pair-device. You get a one-time code; enter it in the desktop app. Pairing is always your act: nothing pairs on its own. -
Talk. In any conversation, ask the agent to join the voice call. It shows up in the app; speak to it.
Supported agents
Any other agent can receive through an HTTP endpoint of its own (SIDEVOICE_DELIVERY_URL).
Status
Beta. What works today: the install above on macOS and Linux, pairing devices with the machine, voice calls with your agents' conversations from the desktop app, interrupting a reply, and replies spoken while the agent keeps working. Reaching your machine from outside your network needs a relay, which is still being built.
The connector's own binaries, published on GitHub Releases, run on macOS on Apple silicon, on Windows x86_64 and on Linux x86_64 and arm64 with glibc 2.28 or newer (Debian 10, Ubuntu 20.04, RHEL 8 and their later releases, and most other distributions since 2019; not musl-based ones such as Alpine).
Commands
The package installs one command, sidevoice (the release archive's binary is sidevoice-connector; same
commands). With --json, a command prints one JSON object on stdout, and a failure as a stable key with an
English message.
connector/README.md describes each command, where things are kept and how the pieces talk
to each other.
The reviewed voice-message MCP integration contract describes intended behavior for a future implementation; it is not a description of shipped support.
When something doesn't arrive or isn't heard
Ask the agent to call the MCP tool voice_diagnose in the conversation concerned. It is read-only and answers
with the versions, whether the core runs and the connector is linked to it, this conversation's
delivery route (and whether its socket exists), its last deliveries with how each ended and whether the agent has
read it, the harness's capabilities and inbound check, the editor bridge state, and where the logs are
(connector.log and core.log in the data directory: ~/Library/Application Support/Sidevoice on macOS, $XDG_DATA_HOME/sidevoice on Linux, %LOCALAPPDATA%\Sidevoice on Windows; SIDEVOICE_DATA_DIR overrides it). It never includes message text, keys or tokens. A delivery that ends
unconfirmed and is never read usually means the agent holds incoming messages (see its inbound check).
Develop
The connector is one Rust binary, the crate in connector/; the build tooling is cargo xtask
(xtask/). You need the Rust toolchain pinned in .github/actions/setup.
cargo xtask fixtures # what the tests run against: the sidevoice-core release pinned by the `sidevoice-platform` workspace tag in Cargo.toml, the pinned Codex CLI
cargo test --locked # unit tests, and the connector against the real core, Codex and the service managers
cargo xtask dist # this machine's release archive, built and verified as a release builds it
# (Linux: needs zig and cargo-zigbuild, to link against glibc 2.28; RELEASING.md)
cargo xtask npm target/dist/sidevoice-connector-<target>.tar.zst && cargo xtask npm-smoke
# its npm packages, installed into a temporary prefix and run (needs Node.js)
cargo xtask testbench # the test bench: talk to a real Claude Code or Codex session through this build, no app
# needed (testbench/README.md)
How a version is built, verified and published (GitHub Releases and npm): RELEASING.md.
Contributing
Issues and pull requests are welcome. Read AGENTS.md first: it holds the rules for code, texts and
tests, for people and coding agents alike. Pull request titles follow
Conventional Commits (CI checks them) and become the squashed commit, from
which release notes are written (RELEASING.md).
Licence
Apache-2.0. The Sidevoice name and logo are trademarks: forks are welcome under their own name — see
TRADEMARKS.md.
Third-party components
The package redistributes its dependencies and the core under their own licences: THIRD_PARTY_NOTICES.md.
