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.

Related MCP server: voice-mcp-server

Get started

You need macOS on Apple silicon, or Linux on x64 or arm64 with glibc (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.

1. Install, on the machine where your agents run:

   npx sidevoice install

   It 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.

2. 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.

3. 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 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, the room pairing, 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 (by default ~/.sidevoice/connector.log and core.log). 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 in core.pin, 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 bench      # the test bench: talk to a real Claude Code or Codex session through this build, no app
                       # needed (connector/README.md, "Test bench")

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.