claude-call 📞

Talk to your Claude Code by voice — a real phone call with your terminal agent.

Not a generic voice assistant. claude-call is voice I/O bolted onto your actual Claude Code session — same skills, MCP servers, memory, and context. You launch it from a project, it resumes the conversation you were just having there, and you keep going by voice. It can read files, run tools, edit code, post to your integrations — everything your Claude Code can do — because the brain is your Claude Code.

  🎙️ mic ─▶ VAD (Silero + Smart Turn) ─▶ whisper.cpp (local STT)
                                              │
                                              ▼
                         claude (daemon, --resume your session)   ◀── the brain IS your Claude Code
                                              │
  🔊 speaker ◀─ edge-tts ◀──────────────── streamed reply (sentence by sentence)

• Local ears (or API): whisper.cpp by default — offline, ~0.6s/utterance (resident server). Or switch to a cloud STT (Groq, OpenAI, ElevenLabs, Google Chirp 2) for top accuracy — see Speech-to-text.
• Your brain: the claude CLI you're already logged into — no separate API key to manage, all your skills/MCP/context. (It does cost — headless usage is billed; see Cost & billing.)
• Free voice: Microsoft edge-tts, many languages — or plug a premium API (ElevenLabs, Cartesia, OpenAI, Rime, Deepgram) if you want.
• One warm process: the brain runs as a persistent daemon for the whole call — context stays cached, replies stream as it talks.

Why it's different

Every other voice agent gives you a fresh, context-less assistant. This one continues your session. Ask it "where were we?" and it knows — because it's literally the same conversation, reached through a microphone instead of a keyboard.

Cost & billing

Read this before you rely on it. The brain is claude -p (Claude Code's headless mode), and headless usage is billed differently from interactive use:

• Interactive Claude Code (you typing in the terminal/IDE) is covered by your flat Pro/Max plan.

• Headless claude -p — what claude-call uses — is not flat. As of June 15, 2026, Anthropic moved claude -p, the Agent SDK, GitHub Actions and third-party apps to a separate monthly agent credit, charged at standard API rates:

  Plan	Monthly agent credit
  Pro	$20
  Max 5×	$100
  Max 20×	$200

  When that credit runs out, automated calls stop unless you enable overflow (pay-as-you-go) billing.

So a voice call costs real money (API token rates) out of that credit. You don't set up a separate API key — it uses your Claude Code login — but it is not "free on top of your subscription."

Keep it cheap:

• CALL_MODEL=haiku — the cheapest brain.
• CALL_CONTINUE=0 — start a fresh session instead of resuming a big one (far fewer input tokens per turn). You lose "continue your session," but it's much cheaper.
• Fewer, longer calls amortize the prompt cache (warm turns cost less than many cold starts).
• Want predictable pay-as-you-go instead? Put ANTHROPIC_API_KEY=... in .env and claude -p bills that directly (no agent-credit cap/stop).

💸 Want it on your flat plan? Use hook mode. voice_hook.py runs the voice loop as a Stop hook on your live, interactive Claude Code session — no headless claude -p. Those turns are interactive usage covered by your flat Pro/Max plan, not the separate agent credit. You drive the voice loop from inside a normal claude session instead of launching call.sh. See Hook mode.

Sources: Anthropic ends flat-rate agent access, June 15 2026 · Use Claude Code with Pro/Max.

Quick install (one command)

curl -fsSL https://raw.githubusercontent.com/caiovicentino/claude-call/main/install.sh | bash

This installs everything — uv, ffmpeg, whisper.cpp, portaudio, the repo, a speech model — and a global claude-call command. It finishes by running claude-call doctor, so you immediately see all green plus a quick latency benchmark. Then, from any project: claude-call.

You still need Claude Code installed and logged in (it's the brain — no API key). macOS also needs Homebrew. Prefer to do it by hand? Follow the step-by-step below.

Step-by-step (from zero)

1. Install the prerequisites

You need four things on your machine:

macOS, one line:

brew install uv ffmpeg whisper-cpp portaudio

⚠️ Claude Code must be logged in. Run claude once and sign in — that's the brain, no separate API key to set up. Heads up: headless use is billed (see Cost & billing).

Linux whisper.cpp (if there's no package): build it and put its binaries on your PATH:

git clone https://github.com/ggerganov/whisper.cpp && cd whisper.cpp
cmake -B build && cmake --build build -j --config Release
export PATH="$PWD/build/bin:$PATH"   # so whisper-server / whisper-cli are found

2. Get claude-call

git clone https://github.com/caiovicentino/claude-call
cd claude-call
./install.sh        # checks prereqs, installs python deps, downloads a whisper model

3. (optional) Make it a global command

ln -s "$PWD/call.sh" /usr/local/bin/claude-call

4. Call

Go into a project you've used with Claude Code, and run it:

cd ~/my-project
claude-call          # or:  /path/to/claude-call/call.sh

It greets you, resumes that project's most recent Claude Code session, and listens. Talk normally; pause ~1s when you finish a sentence (that's the turn detector deciding you're done). Ctrl+C ends the call.

The first run downloads a small Silero model and warms the whisper server. The first spoken turn loads your session context (slower; cached after that).

Commands

Configure

Run the interactive menu — pick your voice (with live preview), speaking style, language, brain model, echo mode and activation:

claude-call config

It writes your choices to .env. Prefer doing it by hand? Every setting is a plain env var:

All settings (.env or env vars)

Full list (STT model & port, greeting, active window, premium keys) is in .env.example.

Premium voices (optional, bring your own key)

Free edge-tts is the default and sounds great. If you want the newest, most realistic voices and don't mind paying the provider, plug in an API key:

Pick it in claude-call config (it asks for the key + voice), or set in .env:

CALL_TTS=elevenlabs
CALL_TTS_API_KEY=sk-...
CALL_VOICE=<a voice id from the provider>

Your key lives only in your local .env. No key = it just uses free edge-tts.

Speech-to-text (local or API)

By default the ears are local — whisper.cpp, offline, free, fast. If you want SOTA accuracy (especially for accents or noisy rooms) you can route STT to a cloud provider:

CALL_STT=groq
CALL_STT_API_KEY=gsk_...        # or set GROQ_API_KEY
# CALL_STT_MODEL=...            # optional override

For Google, auth via gcloud Application Default Credentials and set CALL_GOOGLE_PROJECT / CALL_GOOGLE_LOCATION — no API key. No setting = it stays fully local.

Modes

• Call mode (default): open mic, no wake word — just talk, like a phone call.
• Assistant mode: set CALL_WAKE=claudinha so it only answers when addressed (good for always-on in the background).
• Hook mode (flat-plan): voice loop runs on your live interactive session — see below.

Hook mode (run on your flat plan)

call.sh launches a headless claude -p brain (billed from the separate agent credit — see Cost & billing). If you'd rather stay on your flat Pro/Max plan, use voice_hook.py instead: it wires the voice loop as a Stop hook on a normal, interactive claude session.

How it works: on each turn-stop, the hook speaks the assistant's last message (edge-tts), records the mic until you go quiet, transcribes it (whisper), and feeds your words back as the next turn of the same live session — so those turns count as interactive usage on your flat plan, not headless. Toggle it with the flag file ~/.claude-call-active; say a stop word (encerrar, tchau, desliga, end call) to let the turn stop normally.

Live panel & push-to-talk

• CALL_UI=1 (default): a live terminal panel shows the running transcript, current state (listening / thinking / speaking) and audio levels. CALL_UI=0 to disable.
• CALL_SOUNDS=1 (default): subtle cues for listening / thinking / wake. 0 for silence.
• CALL_HOTKEY=f9: push-to-talk key (held for CALL_HOTKEY_SECS), handy in noisy rooms or when you want explicit control over the mic.

Echo / headphones

Without headphones the mic hears the agent's own voice and loops. Three options:

• CALL_ECHO_GATE=1 (default): half-duplex — mic muted while it speaks. Works on speakers; you can't interrupt mid-sentence.
• Headphones + CALL_ECHO_GATE=0: full-duplex, barge-in works (cut it off any time).
• CALL_AEC=1 (macOS only): real hardware AEC via the OS Voice Processing unit (same as FaceTime) → barge-in on speakers, no headphones. Needs ./build.sh (compiles a small Swift helper) and microphone permission for your terminal. (Built but validate on your machine — it needs a real audio session.)

Latency

A turn is: endpointing (~0.5s of silence to know you're done) → STT (~0.3s, resident whisper-server) → brain (one inference over your session — the dominant cost) → TTS (first audio ~1s on edge; it streams sentence-by-sentence and speaks a quick filler during tool use, so there's no dead air).

To minimize:

• CALL_MODEL=haiku — fastest brain (opus = smartest, slower). The first turn loads your context; warm turns are much faster.
• Premium streaming TTS — Cartesia is ~0.2s to first audio vs edge's ~1s. CALL_TTS=cartesia if latency matters more than the free voice.
• Free edge-tts decodes in streaming mode, so audio starts as soon as the first chunk arrives (not after the whole sentence).

Run claude-call doctor to see your real STT/TTS numbers.

Security ⚠️

Hands-free voice can't answer permission prompts, so the default CALL_PERMISSION=--dangerously-skip-permissions lets the agent run tools / bash / edits without asking. That's powerful and potentially destructive. Only use it on machines/projects you trust. To be asked instead, set CALL_PERMISSION=--permission-mode default — but the call will stall whenever a prompt appears.

Troubleshooting

• Check everything first: claude-call doctor — verifies prerequisites, your model and config, and benchmarks STT/TTS latency (tells you exactly what's missing or slow).
• It doesn't hear me → give your terminal app microphone permission (macOS: System Settings → Privacy & Security → Microphone), then restart the call.
• whisper model not found → ./scripts/download-model.sh small (or point CALL_WHISPER_MODEL at a ggml file you have).
• whisper-server not found → install whisper.cpp (step 1), or set CALL_WHISPER_SERVER=0 to use whisper-cli (slower, no server).
• It hears its own voice / loops → you're on speakers with barge-in on. Use headphones, keep CALL_ECHO_GATE=1 (default), or try CALL_AEC=1 (macOS).
• Replies are slow → the first turn loads your session context; set CALL_MODEL=haiku for snappier turns.
• It starts fresh / "session not found" → you launched from a directory with no prior Claude Code session. Run from a project you've used claude in, or set CALL_SESSION_ID.
• Python 3.13 error → claude-call pins Python 3.12 via .python-version (3.13 removed the audioop module). uv fetches 3.12 automatically.

How it works (the honest version)

The brain is not a daemon that "thinks" continuously. LLMs are stateless: every spoken turn triggers one fresh inference over your conversation, run on Anthropic's servers — exactly what happens when you type in Claude Code. claude-call keeps one claude process alive for the call (stream-json in/out, --resume <your session>), so context stays warm and replies stream — but it's a warm, persistent session, not a continuous consciousness. (One catch: typing in Claude Code is covered by your flat plan, but the headless claude -p this uses is billed separately — see Cost & billing.)

Files

call.py (pipeline) · brain.py (claude daemon) · voice_hook.py (Stop-hook flat-plan mode) · stt.py (whisper-server/cli + API providers) · tts.py (edge-tts + premium providers) · echo_gate.py · audio_meter.py (levels) · ui.py (live panel) · controls.py · hotkey.py (push-to-talk) · sounds.py (audio cues) · session.py (finds your session) · config.py · configure.py (settings menu) · doctor.py (setup check + benchmark) · install.sh · aec_bridge.swift + extras_mac_aec.py (optional macOS AEC).

Credits

Built on Pipecat, whisper.cpp, edge-tts, and Claude Code.

Created by Caio Vicentino. MIT licensed.

🛠️ Built with Cultura Builder

A maior comunidade de builders da América Latina — turning non-technical people into AI builders. 7,900+ builders, 1 year strong, everything built 100% with AI. Come build with us → culturabuilder.com