Skip to main content
Glama

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: pokeclaw

What it depends on

Only a signed-in Claude Code is required. Each of the rest adds something, and the bridge says which are missing, with the exact fix, through its check_dependencies tool and the event API's /api/v1/doctor:

Dependency

What it adds

Claude Code, signed in

everything; required

git

git status on the companion app's cards, and the contribute session

GitHub CLI (gh), signed in

pull requests on the cards, and the contribute session

uv

updating claude-voice and running its tests

Tailscale, with Funnel

reaching the bridge from the phone

a tailnet-only tailscale serve port

the companion app on the phone

the status line writing its figures

the plan's five-hour and weekly bars, and how full each session is

What you can ask for

Tool

What it is for

list_projects

the folders Claude was used in lately, or any folder found by a word from its name

create_session, send_task

start Claude on a task; it answers at once and works in the background

session_recap

where one session stands, short enough to read aloud

whats_new

only what happened since you last asked: finished, failed, waiting for you, or a reply a session sent back to a message

fleet_recap

every session in one call, each with a line on what it is doing

get_active_session, set_active_session

the session the owner talks to, chosen on the companion page or by voice

check_dependencies

which dependencies are missing for full use of the bridge, and the exact fix for each

update_bridge

update claude-voice: pull, install, test, restart, and roll back if anything fails

update_changes

what an update would bring: the new commits on GitHub, grouped by kind

health

the bridge's own state: uptime, version, memory, calls and errors per tool, courier and watcher, and whether developer mode is on

plugin_restart

start one plugin again with its new code, without restarting the bridge; its tools come back only if they take what was approved

developer_mode_request, developer_mode_confirm, developer_mode_off

switch developer mode on by voice with a question and your yes (only from the Claude app; it ends by itself after eight hours), or off at once

plugin_approve_request, plugin_approve_confirm

in developer mode, approve a plugin whose tools changed: the voice names each changed tool and approves on your yes

list_pending_approvals, approve, deny

answer Claude's requests to edit files, run commands and so on

answer_question

answer a session's choice box by voice, by an option's number or label or in your own words, while the phone hook waits on it; list_pending_approvals lists these questions, and whats_new reports each as needs_answer

cancel, close_session

stop a turn, retire a session

list_sessions

the sessions this bridge started, and every one running on the computer

session_tree

the sessions as a tree, including which ones have been messaging each other

org_chart

who handles what: each programme's roles, who fills them and whether they run, from the org chart; a session can then be named by its address, such as voice/manager

list_active_sessions

every Claude Code session running on the computer now, terminal or background

start_active_session

start a new Claude Code session in the background, ready to talk to at once; with create_folder, a new project folder by a plain name under the root, only when asked

start_role

start a session for a role, such as contribute: say what to change in claude-voice and get a pull request

stop_active_session

stop such a session again; sessions the bridge did not start are never stopped

rename_session

give a running session a new name; messages to the old name still reach it, and in tmux an idle session is renamed in Claude Code too

message_active_session

send a message into a session that is open in a terminal; answered sending when delivery outlasts the caller's time budget, and finished in the background

ask_active_session

ask such a session something and wait for its answer, as if talking to it directly

wait_for_session

wait, sending nothing, until such a session's turn ends or it needs its user, then hear its reply

side_question

a quick answer about a busy session, read from what it wrote lately, never sent into it

digest_session

a long conversation summed up, or a question about it answered, in a few sentences

refresh_session_summary

a fresh summary of a session (the chosen one by default), shown on its page in the companion app too

read_session_output, search_session_history

read what such a session said lately, or search everything it said

list_claude_conversations, attach_conversation

continue an earlier conversation, as a copy run by the bridge

The companion app

claude-voice-ui is a phone app, built as its own project, that sits beside the voice. It shows every session as a card. Tapping one makes it the session the voice talks to, and while you talk it shows what that session last wrote and whether it waits for you. It reads the bridge only through the event API: a few JSON endpoints and one stream of live events, behind the bridge's own login. Any other app can use the same API.

The app and the API answer only this computer and your tailnet, never the internet through Funnel. To open it on the phone:

  1. Clone and build the app (its README says how), and set CLAUDE_VOICE_UI_DIR in ~/.config/claude-voice/env to its built folder; deploy/install.sh does this when it finds ../claude-voice-ui/dist. Restart the service.

  2. Give the bridge a port that only the tailnet reaches. Choose one or both:

tailscale serve --bg --https=8814 http://127.0.0.1:8811
tailscale serve --bg --tcp=8813 tcp://127.0.0.1:8811
  • https://<machine>.<tailnet>.ts.net:8814/ui/ works when the phone can look up the computer's tailnet name.

  • http://<the computer's tailnet address>:8813/ui/ works even when it cannot. It must be a TCP forward, because Tailscale's web ports answer only by name. The tailnet encrypts the traffic either way.

  1. Name the address you will open in CLAUDE_VOICE_UI_ORIGINS, for example http://100.x.y.z:8813, so a change made in the app is accepted.

--bg keeps the ports across restarts. The bridge's check_dependencies tool and /api/v1/doctor say whether such a port is there.

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.

check also reads the environment file the service loads, ~/.config/claude-voice/env, when it exists. systemd reads that file, and so does a shell that runs set -a; . ~/.config/claude-voice/env. A line the two would read differently is a warning, not a stop. An unquoted value with a space is one: the shell runs its second word as a command. So is an unquoted shell character ($ ` ; & | < > ( ) and quotes, a backslash, or # after a space), an unclosed quote, or a line that is not KEY=value. Each warning names the line and its KEY, never the value:

claude-voice: note: env line 4 (SOME_KEY): the value has a space and no quotes. Put the value in double quotes: SOME_KEY="…"

The bridge logs the same lines as warnings when it starts, and starts anyway.

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.

Variable

Default

Meaning

CLAUDE_VOICE_ROOT

~/src

Claude may only be started in folders under here

CLAUDE_VOICE_TOKEN

—

required over HTTP, at least 32 characters; it is also the login secret

CLAUDE_VOICE_PUBLIC_URL

https://<first public host>

the address clients reach the bridge at

CLAUDE_VOICE_PUBLIC_HOSTS

—

comma-separated hostnames the tunnel serves

CLAUDE_VOICE_HOST / _PORT

127.0.0.1 / 8811

keep it on this computer and tunnel in

CLAUDE_VOICE_COURIER_NAME

Owner via claude-voice

the sender name a session sees when the voice messages it, e.g. Roy via stemmen

CLAUDE_VOICE_UI_ORIGINS

—

comma-separated origins of a companion app served elsewhere, allowed to call the event API across sites

CLAUDE_VOICE_UI_DIR

—

a folder with a companion app's built files, served at /ui/

CLAUDE_VOICE_DB

~/.local/state/claude-voice/bridge.db

where sessions and events are kept

CLAUDE_VOICE_ENV_FILE

~/.config/claude-voice/env

the environment file check and the bridge look over for lines a shell would misread

CLAUDE_VOICE_ACCESS_TOKEN_SECONDS

3600

how long a sign-in's access token lasts before the app must refresh it; set it to a week (604800) on a computer that sleeps, since the Claude app gives a connector up after about an hour of failed refreshes

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.

  • Starting a new attempt does not start the count again: after five wrong secrets in ten minutes, across every attempt, the page refuses every try, the right secret too, for ten minutes. Apps already signed in keep working; only a new sign-in waits.

  • A lockout within a day of the last one lasts twice as long: ten minutes, then twenty, forty and so on, up to a day. A day without a lockout starts again from ten minutes. The page says how long is left.

  • The bridge keeps the lockout and the count of wrong secrets only in memory, so restarting the bridge ends a lockout at once.

  • Anyone may register an app, so the bridge keeps no endless list of strangers: an app that never signs in is forgotten after an hour; while twenty such apps wait, registering stops; and while twenty sign-ins are open, a new one is refused until they expire ten minutes later. Apps already signed in are never affected.

  • Access tokens last an hour.

  • Refresh tokens last 90 days and are replaced each time they are used. A replaced one still works for a minute, because an app may refresh twice at once.

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

To restart the service on purpose, say why, so health can tell the voice:

$ claude-voice restart --why "a new plugin" --dry-run
claude-voice: would note a planned restart "a new plugin", then run: systemctl --user restart claude-voice

Without --dry-run it writes the reason to ~/.local/state/claude-voice/restart-reason.json and restarts. update_bridge writes one too, with the commits it moved between. The next start reads the file and deletes it. health then gives last_restart as at, reason, by, changes (commits since the start before), from, to and note. The note is the --why text, cut to one line of at most 120 characters. A note over ten minutes old is ignored, and the log says so. The reason is one of these:

  • planned, update or rollback, from a reason file under ten minutes old;

  • crash, when systemd started it again by itself;

  • boot, when the computer has been up under five minutes;

  • unplanned, for anything else, such as a plain systemctl --user restart.

Answer questions and approvals from the phone

With the companion app open, a session's choice box or permission prompt can be answered on the phone instead of at the terminal. A hook in your Claude Code settings hands it to the bridge; with the app closed it steps aside and the box shows in the terminal as before. Install it once, with the bridge's own Python:

uv run python -m claude_voice.phone_hook --install

It merges two hooks into ~/.claude/settings.json, keeps everything already there, and saves the old file as settings.json.bak. The app and the API answer only this computer and the tailnet, behind the login, and every answer is logged. Anyone signed in to the app can approve commands on this computer, so sign in only on your own devices.

Only a prompt reaches the phone. In Claude Code's auto mode, most actions are decided without asking, and an action its safety check refuses is simply refused: there is nothing to answer, on the phone or anywhere else. To have such an action asked about instead, list it under ask in your settings. That is a choice for each owner. For example, to be asked before a force push rather than have it refused:

{ "permissions": { "ask": ["Bash(git push --force-with-lease *)"] } }

Keep the patterns narrow. An ask rule is a door the phone can open, and anyone signed in to the app holds the key. Put a rule meant only for you in a project's .claude/settings.local.json, which stays out of git, rather than in its shared .claude/settings.json.

Where your clones are

The bridge works out where the project's repositories are, on GitHub and on this computer, and the defaults suit a clone of this repository with the companion app next to it. To change any of it, for example to work from a fork or to keep the clones elsewhere, write ~/.config/claude-voice/config.toml (another file can be named in CLAUDE_VOICE_CONFIG):

voice_instructions_file = "~/.config/claude-voice/voice-instructions.md"  # your own rules for the voice

[repos]
claude_voice = "roykollensvendsen/claude-voice"        # the project, on GitHub
claude_voice_ui = "roykollensvendsen/claude-voice-ui"
fork = "you/claude-voice"                               # your fork, if you have one

[paths]
claude_voice = "~/src/claude-voice"          # default: the clone the bridge runs from
claude_voice_ui = "~/src/claude-voice-ui"    # default: next to it
ui_dist = "~/src/claude-voice-ui/dist"       # default: inside it; CLAUDE_VOICE_UI_DIR wins
contribute = "~/src/claude-voice"            # the contribute session's clone; default: claude_voice
claude_voice_mobile = "~/src/claude-voice-mobile"  # the phone app's clone; default: next to it

[sessions]
remote_control = true                        # a started session can be opened in the Claude app
launch = "terminal"                          # or "background"
terminal_command = "kitty --directory {cwd}" # default: gnome-terminal, kgx, konsole or xterm, the first found

[budgets]                                    # seconds each kind of client is answered within
claude_app = 10
voice_app = 120
default = 60

A session the bridge starts opens in a terminal window on your desktop, so you can watch it and type into it, and with Remote Control, so the Claude app on your phone can open it too. Without a desktop it opens in tmux (tmux attach reaches it), and with no terminal at all in the background. The companion app's settings page changes remote_control and where sessions start, and one start can ask otherwise; the terminal command is set only here.

Each kind of client is answered within its own time budget, set in a [budgets] section. The Claude app drops a tool call after about 30 seconds, and its clock may already have run while it reconnected, so it gets 10 (claude_app). The voice app waits longer and gets 120 (voice_app); anything else gets default, 60. A message that takes Claude Code longer to deliver is answered "sending" and delivered in the background. Its say tells the caller the message is on its way but not yet confirmed, and that the session's output shows whether it arrived. A wait for a session's answer ends at the budget with "still working".

Your own rules for the voice go in the file voice_instructions_file names, outside this repository: which session takes your proposals, which role answers small questions, how you like to be spoken to. The bridge adds its text to the voice's instructions under "The owner's own rules:". Keep the setting at the top of the file, before any [section], or TOML reads it as part of that section. Without it the voice gets the general rules only. A file that cannot be read never stops the bridge: the log names the path and what to do. Only the first 8 KB is used, and the log says when a file was cut. A starting point, with placeholders, is docs/examples/voice-instructions.md. The file is read when the bridge starts, so restart it after a change.

The update works in claude_voice. The contribute session works in contribute, and sends its pull request to repos.claude_voice; it may push only to your fork. The doctor checks that every folder exists, is a clone, and points at the right repository or your fork, and says how to fix it if not.

Send a change back

Ask the bridge for a contribute session, by voice or in the companion app, and say what you want changed. It works in your own clone, makes a fork under your GitHub account if needed, runs the tests and opens a pull request here. It cannot push to this repository itself. CONTRIBUTING.md has the rules it follows, which apply to any change.

Develop

CONTRIBUTING.md has the gates and how a change is made. Once per clone, uv run claude-voice permissions gives Claude Code the rules for the voice repositories: what it may run without asking, what it must ask about first, and what it may never run (docs/permissions.md). 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

Skills

A skill is a set of written steps that Claude Code follows for one kind of task. These come with the clone, in .claude/skills/, and Claude Code offers them as soon as you open it in this folder; type / to see them by name.

Skill

When it is used

What it does

write-plugin

Making a local tool reachable by voice

Writes or wires up a plugin, and adds, approves or changes one

code-quality

A measure on the code-health page is amber or red

Measures it locally, fixes the worst one test-first and lands the fix

write-commit

Every commit and every pull request description

Writes the message for a reader who has never seen the project

review-contribution

A pull request comes from outside the project

Reviews it, runs its code only in a sandbox, merges it and thanks the author

org-chart

Sessions that belong together should show as one programme

Writes the programme file the bridge's org chart reads, after the owner's yes

manage

You are the session the owner talks to about the bridge and its plugins

Keeps the overview, passes decisions on and collects the owner's questions

The last two are for running several sessions as an organisation, and are optional.

Plugins: other local tools for the voice

A plugin is another MCP server on this computer whose tools the voice may call through the bridge, behind the same sign-in. Nothing changes until you add one. Name it in the settings file, with the tools the voice may call; any other tool it has stays out of reach:

[plugins.garage]
command = "uv"
args = ["run", "garage-door-mcp", "--secrets-file", "firmware/secrets.yaml", "--host", "192.168.0.46"]
cwd = "~/garage-door"
tools = ["garage_status", "garage_request", "garage_confirm"]
timeout = 30          # seconds a call may take
branch = "main"       # the branch its checkout follows, for approving by voice (default main)

Then approve it by typing its name. A bridge that is running picks the approval up within a few seconds and offers the plugin's tools without restarting; connected clients are told the tool list changed:

claude-voice plugins approve garage

The approval covers exactly that command, folder and list of tools, what each tool takes as the plugin describes it then, and every word the voice reads from the plugin: each tool's description and the plugin's own instructions. Once approved, the command starts the plugin and prints those inputs and words. Change any of them, or let the plugin give a tool a new input or rewrite what a tool or its instructions say, and it must be approved again: until then the bridge offers none of its tools and logs why. claude-voice plugins list starts each plugin and checks it the same way, so it says approved only when a restart would offer the plugin's tools. The bridge never holds a plugin's secrets: the plugin reads its own, and starts with only a small default environment. Each plugin runs as a process of its own, started again after a failure, and a call that runs past timeout is cut off. Its tools reach the voice named after it (garage_status), its safety rules stay inside it, and the health report shows each plugin's state.

Once a plugin is approved, three things can happen to it (ADR-CV-010):

  • New code, the same tools taking the same inputs. It runs without asking, and the log names the commit. plugin_restart starts one plugin again with its new code, without restarting the bridge or dropping the call. The new one must list its tools within 60 seconds, or its own timeout when that is longer. If it does not, it counts as not started, never as changed: the one running stays offered, and the voice says to try again.

  • A tool added, removed, taking new inputs, with a changed read-only mark, or with new words for the voice in its description or the plugin's instructions. You can type the approval as above, or approve it by voice in developer mode. You switch that on by voice: the voice asks, you say yes. It ends by itself after eight hours, can be switched off at once from anywhere, and health and the work page show it. The voice then names each changed tool and approves on your yes. It works only from the Claude app, never from a program on this computer, and only when the plugin's checkout is clean and level with the branch it follows (branch). Any file git does not know about counts as unclean, a backup included, so keep such files out of the plugin's folder or list them in its .git/info/exclude.

  • A new plugin, or a new command or folder. Always typed, as above.

To take an approval back, run claude-voice plugins revoke garage. A running bridge stops offering the plugin's tools within a few seconds, and it waits for a typed approval again.

An approval written by an older version of the bridge did not cover the words the voice reads. So after upgrading, every plugin waits for one more approval, typed as above or by voice in developer mode, because its command and folder are still known. Until then its tools are not offered, and claude-voice plugins list says tools changed.

Installing a plugin in one command

A plugin that ships a manifest (docs/plugin-manifest.md) is installed from its checkout in one go, instead of the steps above by hand:

claude-voice plugins install fuel --from ~/fuel-mcp --dry-run   # shows each change, writes nothing
claude-voice plugins install fuel --from ~/fuel-mcp             # does it, step by step

Each step is numbered and names the file it changes:

  1. It reads the manifest. The checkout must be a clean git checkout on the manifest's branch. If the folder is missing, it prints the git clone command for you to run; it never fetches anything itself.

  2. It adds the plugin's entry to the settings file, after a backup. The entry is written as TOML by a library, so no text in the manifest can add another table, and the result must read back as your old file plus exactly that entry. If an entry by that name is already there and differs, it changes nothing and shows the difference for you to edit by hand.

  3. When the plugin uses the shared home position and there is none yet, it asks for it, as home set does.

  4. It writes the plugin's own config to ~/.config/<dir>/config.toml, from the default the plugin ships, and asks only for the values the manifest marks as yours, without showing them. A config that is already there is kept. It writes nowhere else: never through a symlink, never outside that folder, never inside a git repository, and it asks first when no known plugin uses the folder.

  5. It ends with the usual typed approval, or says the plugin is already approved.

The summary at the end lists each file it changed, where the backup is and the exact command that undoes it. A second run changes nothing. A dry run shows each file's difference with your values masked, and asks nothing. It asks you questions, so it runs only in a terminal of your own:

$ claude-voice plugins install fuel --from ~/fuel-mcp
claude-voice: plugins install asks you questions; run it in a terminal of your own, not from Claude Code or through a pipe.

To list them:

$ claude-voice plugins
No plugins in the settings file.

One home position for every plugin

A plugin that needs to know where home is, such as a weather or fuel price plugin, reads one shared file: ~/.config/claude-voice-home/home.toml, readable by you alone. It holds only lat and lon, rounded to 2 decimals (about 1 km), and it is outside the bridge's own config and every repository. Each plugin is told the file's path in its own config, as home_file, and reads it itself; the bridge passes it nothing, and nothing looks the position up from the network.

claude-voice home set asks for latitude and longitude, typed or pasted from your phone's map, without showing them. Each must be a number inside Norway (57 to 72 north, 4 to 32 east) unless you add --anywhere. It keeps one backup, of the file it replaced, and prints the command that undoes the change. It refuses when the file would land inside a git repository, as it would if ~/.config linked into a dotfiles repository. That check finds a .git folder above the file, so it cannot see a dotfiles tool that keeps its repository elsewhere: never add ~/.config/claude-voice-home to a dotfiles tool such as yadm or vcsh. A folder others could list is narrowed to owner-only, and it says so. Every plugin sees the new position at its next read. It asks you questions, so it runs only in a terminal of your own:

$ claude-voice home set
claude-voice: home set asks you questions; run it in a terminal of your own, not from Claude Code or through a pipe.

Another machine

Any other computer you own can be reached through this one. It runs a small claude-voice of its own, the agent, which this bridge calls over Tailscale; its tools, and with sessions turned on its Claude Code sessions, reach the voice with the machine's name in front. The agent listens on its Tailscale address only, answers only the bridge it was paired with, and offers nothing about the bridge itself. Setting one up, pairing it and what to do when it fails are in docs/other-machines.md.

$ claude-voice agent --help
usage: claude-voice agent [-h] [--sessions] [{serve,pair,install}]

positional arguments:
  {serve,pair,install}  serve (the default), pair, or install as a service

options:
  -h, --help            show this help message and exit
  --sessions            with install: offer this machine's sessions

To list the machines this bridge knows:

$ claude-voice machines
No machines in the settings file.

Acknowledgements

  • kelno measured that the Claude app drops a tool call after about 30 seconds, and capped waiting calls in their fork; the time budgets here come from that idea. Several earlier changes came from their fork too.

  • AndresSM415 reported, with care and with fixes, that the sign-in could be guessed at without end and that strangers could register apps without limit (issues #75 and #76).

Licence

GPL-3.0-or-later. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Wraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.
      4
      57 npm
      21
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.
      4
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables ISLI agents and MCP clients to dispatch natural-language coding and terminal tasks to a locally-installed Claude Code CLI, supporting both one-shot execution and persistent sessions with workspace and security controls.
      -