claude-voice

Talk to the Claude Code sessions on your own computer from your phone.

You speak to a voice assistant (Claude's mobile app in voice mode is the one this was proven with). The assistant calls this bridge over the internet, and the bridge does the work on your computer:

• it starts and follows Claude Code sessions there;

• it passes your messages into sessions already open in a terminal;

• it reads back what they did.

Claude Code runs under your own Claude subscription, not a pay-per-use API key. Anything risky, such as editing files or running commands, waits until you say yes.

The bridge is an MCP server: a program offering named tools that an AI assistant can call.

voice assistant on the phone (Claude app, voice mode)
   │  custom connector, signed in with OAuth
   ▼
public HTTPS address (e.g. Tailscale Funnel)
   ▼
claude-voice on your computer
   ├─ sessions it runs itself ──► Claude Agent SDK ──► Claude Code
   └─ sessions open elsewhere ──► Claude Code's own session messaging and transcripts

Start here: five minutes on one computer

You need Linux or macOS, a Claude subscription (Pro or Max), and an internet connection. Nothing else has to be installed first. An assistant doing this for you should read AGENTS.md first.

curl -LsSf https://astral.sh/uv/install.sh | sh          # uv, which installs Python tools
curl -fsSL https://claude.ai/install.sh | bash           # Claude Code
export PATH="$HOME/.local/bin:$PATH"
uv tool install git+https://github.com/roykollensvendsen/claude-voice
mkdir -p ~/src                                           # the bridge only works in folders under here
claude-voice check

check now says that Claude Code is not signed in. Run claude, type /login, sign in with your Claude account, and run claude-voice check again. It should print ready to serve over stdio. Your projects belong in ~/src; to use another folder, set CLAUDE_VOICE_ROOT (see the settings).

Then connect it to Claude Code on the same computer:

claude mcp add --scope user claude-voice -- claude-voice serve

Start claude in any folder and ask: "Which Claude Code sessions are running on this computer?" The answer comes from the bridge. In Claude Desktop, add this to its configuration file instead (Settings → Developer → Edit Config), with the full path that which claude-voice prints:

{ "mcpServers": { "claude-voice": { "command": "/home/you/.local/bin/claude-voice", "args": ["serve"] } } }

That is the whole bridge, used locally. The next two steps let you reach it from a phone: run it as a service, then give it a public address.

Related MCP server: claude-code-mcp

What you can ask for

How it behaves

• One bridge session is one Claude conversation.

  • Each prompt resumes that conversation, so it survives restarts of the bridge.

  • A session that was in the middle of a turn when the bridge stopped is marked interrupted.

• Your subscription, not the API. The bridge refuses to start while ANTHROPIC_API_KEY is set, because Claude would then be billed per token. Set CLAUDE_VOICE_ALLOW_API_KEY=1 if that is what you want.

• Your own Claude Code settings apply, including your permission rules. Nothing is pre-approved beyond them.

• Risky actions wait for a yes.

  • Anything Claude Code would normally ask you about becomes a pending approval with a short number you can say aloud, such as "approval 3: Bash, rm -rf build".

  • Reading files needs no approval.

  • A request nobody answers is refused after ten minutes.

• A session open in a terminal is never taken over.

  • Messages are delivered into it, the way one Claude Code session messages another.

  • Continuing such a conversation from the bridge makes a separate copy, and the two then carry on independently.

  • The bridge never stops a terminal session.

• Projects are confined to CLAUDE_VOICE_ROOT. Folders outside it are refused.

Know the trust boundary. Signing in proves that the caller is your assistant. It cannot prove that you said yes to a particular action. The assistant is told to approve only on a clear spoken yes, but a misbehaving one could approve on its own. Keep your Claude Code permission rules sensible, and guard the login secret like an SSH key.

Settings

check says whether the bridge could start, without starting it. It also asks Claude Code whether it is signed in. When something is missing, it says how to fix it, and when all is well it prints ready to serve. check --json lists every check, for an assistant doing the setup:

$ env -u ANTHROPIC_API_KEY -u CLAUDE_VOICE_ALLOW_API_KEY CLAUDE_VOICE_ROOT=no-such-folder claude-voice check
claude-voice: CLAUDE_VOICE_ROOT is not a directory: no-such-folder. Make it with `mkdir -p no-such-folder`, or set CLAUDE_VOICE_ROOT to the folder that holds your projects.
$ env -u CLAUDE_VOICE_ALLOW_API_KEY CLAUDE_VOICE_ROOT=src ANTHROPIC_API_KEY=sk-ant-example claude-voice check
claude-voice: ANTHROPIC_API_KEY is set, so Claude would bill the API instead of your subscription. Unset it, or set CLAUDE_VOICE_ALLOW_API_KEY=1 if that is intended.

serve runs it. Over HTTP it refuses to start without a login secret:

$ env -u ANTHROPIC_API_KEY -u CLAUDE_VOICE_TOKEN CLAUDE_VOICE_ROOT=src claude-voice serve --transport http
claude-voice: CLAUDE_VOICE_TOKEN must be set to serve over HTTP. Make one with `export CLAUDE_VOICE_TOKEN=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')`.

With a secret it listens on http://127.0.0.1:8811/mcp:

export CLAUDE_VOICE_ROOT=~/src
export CLAUDE_VOICE_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
uv run claude-voice serve --transport http

serve --transport stdio is for a local MCP client on the same computer. It is also the default.

Signing in

GET /healthz answers anyone. /mcp needs one of two things:

• an OAuth access token, which is how phone apps connect;

• the login secret itself, sent as Authorization: Bearer …, for local tools.

When an app connects, it registers itself and sends you to a sign-in page on the bridge. You type the login secret there once.

• Each sign-in attempt allows five tries.

• Access tokens last an hour.

• Refresh tokens last 90 days and are replaced each time they are used.

• Tokens are stored only as hashes.

Run it as a service and reach it from the phone

This step needs Linux with systemd; on macOS, run claude-voice serve --transport http in a terminal for now. The script lives in the repository, so clone it first:

git clone https://github.com/roykollensvendsen/claude-voice && cd claude-voice
deploy/install.sh
journalctl --user -u claude-voice -f

The script installs a user service that starts with your login. It also writes a fresh login secret to ~/.config/claude-voice/env, readable only by you.

The phone needs a public HTTPS address. With Tailscale, first enable Funnel for the machine in the admin console, then:

tailscale funnel --bg --https=443 http://127.0.0.1:8811

The bridge is then at https://<machine>.<tailnet>.ts.net/mcp. Use port 443: claude.ai could not reach the bridge on port 10000.

In the Claude app, add a custom connector with that address and connect. Then set the tools to always allow, so the app does not ask before each one. ChatGPT on a Plus plan could not connect to a custom MCP server from Android at the time of writing.

Develop

CONTRIBUTING.md has the gates and how a change is made. In short:

• Tests are written first, and run against a scripted stand-in for Claude, so they need no account.

• A separate set runs against a real signed-in Claude Code. It uses a little of the subscription and never runs in CI:

uv run pytest -m e2e

Licence

GPL-3.0-or-later. See LICENSE.