voicehook-agent
Talk to your coding agents instead of reading their output.
voicehook.ai is a voice call in the browser. Hit "invite agent", hand the link to Claude Code, Codex or opencode, and talk to it while it keeps working. Delta, the voice in the call, answers from the status board and FAQ your agent keeps up to date, so you hear what is going on without opening a terminal.
This repo holds the agent side: the voicehook-join Claude Code plugin and the
voicehook-agent CLI that lets any agent with a shell join a call.
Three ways to connect
| Your agent | How to connect |
|---|---|
| Claude Code | Plugin, two commands (see below). Details |
| claude.ai / Claude Desktop | Custom connector https://voicehook.ai/mcp (Settings, Connectors, Add custom connector; no key). Guide |
| Any agent with a shell | Quickstart A (HTTPS bridge, nothing to install) or the CLI |
Which one? MCP (connector or plugin) is the entry: nothing to install, one agent per call, the only path with
create_call, cards and decisions. The CLI is the pro tool for multi-agent work on one machine. The
HTTPS bridge is the protocol underneath and the fallback.
MCP/bridge = one agent in the call; activity lines are only what that agent writes by hand. For several agents/sessions on one machine working on one call, use the voicehook-agent CLI (pro): its multi-session relay + Claude Code hook feed the live activity log, status and decisions of ALL local sessions into the call automatically. MCP/bridge run on the server and cannot see the user's local sessions.
| path | role | use it when |
|---|---|---|
MCP (voicehook.ai/mcp) |
entry + distribution | a single agent in a call, cloud/sandbox sessions, starting a call yourself |
CLI (voicehook-agent) |
pro tool for multi-agent work | several agents/sessions on one machine in one call, live activity log of all sessions |
Bridge (/api/bridge/*) |
protocol underneath + fallback | no MCP client and no CLI |
Details and install without git: docs/CLI.md.
In Claude Code:
/plugin marketplace add voicehook-ai/voicehook-agent
/plugin install voicehook-join@voicehook
Once connected, paste an invite link (https://voicehook.ai/r/<slug>?invite=<code>)
into your agent and it joins the call.
MCP tools (connector and plugin):
| tool | what it does |
|---|---|
create_call |
start a new call for your user (main agent only: never delegate create_call to a subagent, the link would stay in its thread): human_url plus share_text (pass it on verbatim: open the link in a normal browser, not an app's built-in browser) |
join |
join a call from an invite link with your chip label; greets for you in the call language (greet, default on); returns the session, the call language and the call context (first_actions); before the person opened a create_call link it returns waiting_for_human: call it again |
next |
wait up to 50 s for the next turn (user, decision, operator, context, ended); call it at least every 10 to 15 s, one loop per agent; after a pause it brings missed |
say |
the voicebot speaks the text |
status |
status board (never spoken) the voicebot answers from, optional chip emoji |
show |
a card on the call page (text, code, link or image), never spoken |
activity |
one line of 3 to 8 words for the activity feed, on every step |
decide |
a question for the Decision Board (yes/no or up to 3 options); the answer comes back in next |
leave |
leave the call |
On 5xx, 503 or a network error the agent simply calls the tool again after 2 s; the session stays valid. Several agents in one call: rules.
CLI quickstart
uvx voicehook-agent join 'https://voicehook.ai/r/<slug>?invite=<code>' --name <your-own-name> --model <your-model-name>
--nameand--modelare mandatory: a display name the agent picks for itself and the exact model it runs on. Name your real model and vendor, never "Claude" unless you are Claude.- Use the full invite link, including
?invite=<code>. - stdout prints what the user and the voicebot say; every line on stdin is spoken.
For a loop without polling (say, next, status, leave), the status board, the activity
hook and all flags see docs/CLI.md.
Several Claude Code sessions on one machine (0.15.0): run voicehook-agent hook install
once; while one session is in a call, every other session reports turn goal, PR, deploy
and errors under its own name in the call's activity feed
(multi-session relay).
Since 0.16.0 such a helper session can also ask the human (decide, answer via
relay-next or decide --wait) and keep its own status board (status --doing ...)
(helper sessions).
Pricing
About 10 minutes free every day. Prepaid from 10 EUR, no subscription.
Documentation
| Document | Contents |
|---|---|
| docs/CLI.md | Install, agent loop commands, status board and FAQ, speaking style, activity feed and hooks, shapes, self-update, Claude Code plugin, skill registration |
| docs/PROTOCOL.md | stdin/stdout protocol, data-channel topics, relay flags, HTTPS bridge, wake marker, server behaviour, environment variables |
| docs/DEVELOPMENT.md | CI jobs, plugin releases, CLI releases, PyPI setup |
| OPERATOR-PROTOCOL.md | Server-side operator protocol (voicehook.ai) |
Development, CI and releases
CI runs tests, ruff, plugin validation, a secret scan and a skill drift check on every PR. Release tags, the plugin release checklist and the PyPI setup are in docs/DEVELOPMENT.md.
License
MIT, see LICENSE.
Made in Germany, hosted in Nuremberg (Hetzner). No cookies, no tracking, no call recordings. Nothing you or your agent say is stored. Privacy policy
1 maintainer
Metadata
1 maintainer
Release files for voicehook-agent 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| voicehook_agent-0.18.0.tar.gz | 111.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| voicehook_agent-0.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 231.7 kB
Release files / voicehook_agent-0.18.0.tar.gz
| Download URL | voicehook_agent-0.18.0.tar.gz |
|---|---|
| Size | 111.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c44a9c77dae452f14af24573ae9bd22dce507a0decf27c13ec3b837afa618d5f
|
|
BLAKE2b-256 checksum How to use checksums |
f188684150b62b3f69d0b94446fcfbb3ad8a2409598fc9ccc13c08260e997864
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / voicehook_agent-0.18.0-py3-none-any.whl
| Download URL | voicehook_agent-0.18.0-py3-none-any.whl |
|---|---|
| Size | 120.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8a53f94b26cb2d428e273fa54b868e61092f70234b4ee32bbeef3aff0c4eb74
|
|
BLAKE2b-256 checksum How to use checksums |
8de64c8b4a7fb9405e6d22323728ff47ec08997a7b4847ba98e165a036e8a311
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logSecurity for voicehook-agent 0.18.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for voicehook_agent-0.18.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
