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

What you can ask for

Related MCP server: claude-code-mcp

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.

Run it

You need Python 3.12 or newer, uv, and Claude Code signed in with your account (run claude, then /login).

check reads the configuration from the environment and says whether the bridge could start, without starting it:

$ env -u ANTHROPIC_API_KEY -u CLAUDE_VOICE_ALLOW_API_KEY CLAUDE_VOICE_ROOT=src claude-voice check
claude-voice: ready to serve over stdio; projects under src
$ 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

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

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.