Troubleshooting

Look at the state line under the transcript:

• The level bar stays flat: macOS has not given claudio the microphone. Open System Settings, then Privacy & Security, then Microphone, and turn it on for the app claudio runs in: your terminal app, or bb when its panel starts claudio. Restart claudio.
• It reads muted · say /unmute: say “slash unmute”, or type /unmute.
• It reads push to talk · Enter opens the mic: press Enter before you talk, or turn push to talk off with claudio set push_to_talk false.
• Your words show dim: address_me is on, so only turns that start with its name count (“claudio”, or the name you gave it). Say the name and “slash address me off”, or run claudio set address_me false.
• It reads ears lost · reconnecting: see ears lost.

claudio cannot reach Deepgram Flux. It retries after 1, 2, 4 and 8 seconds, then every 15 seconds, until it connects.

Check your connection, then check the key with claudio doctor. If it never reconnects, check the ears setting: it must be a Flux model, such as flux-general-en.

Your turn ends too early. Wait longer for it:

claudio set eot 0.8
claudio set eot_timeout_ms 2500

Listening and turns explains both settings.

Your turn ends too late. End it sooner:

claudio set eot 0.6

If it still waits, lower eot_timeout_ms to 1000.

The banner reads echo cancel off, so the mic hears the speakers. Pick one fix:

• Install the Xcode command line tools with xcode-select --install, then restart claudio. It builds the echo canceller once.
• Use headphones.
• Turn barge-in off with claudio set barge_in false, and cut replies with Enter.

swiftc failed to build the echo canceller. The warning ends with the compiler's last lines. claudio carries on with the plain mic, so barge-in needs headphones.

Reinstall the Xcode command line tools with xcode-select --install, then restart claudio. It tries the build again on every start until it succeeds.

The echo canceller exited while claudio ran, and claudio switched to the plain mic and speaker for the rest of the run. The text after stopped: is the last line of helper.log. Until you restart, barge-in needs headphones.

If it stops on every run, delete the built helper so it is rebuilt on the next start:

rm ~/.config/claudio/bin/claudio-audio

The reply took more than 3 seconds from the end of your turn to its first word. The state line shows this time for a few seconds after each reply. To speed it up, from most to least effect:

• Lower the effort, if you raised it: claudio set effort low.
• Pick a faster model: claudio set model haiku or claudio set model sonnet.
• Let the brain start earlier: claudio set eager_eot 0.2.

You see one of these:

• ! mouth lost: the speech service is unreachable; text only
• ! mouth lost mid-reply; the rest is text only

claudio could not connect to the speech service, twice, one second apart. The reply is shown as text, and the next reply tries again. Check, in order:

1. Your connection.
2. The voice name, which claudio does not check: claudio set voice aura-2-orion-en restores the default.
3. For ElevenLabs, the elevenlabs_api_key in secrets.json and the elevenlabs_voice id. claudio set mouth deepgram switches back to Aura.

mouth is elevenlabs, but claudio has no ElevenLabs key, so Deepgram speaks instead. Add elevenlabs_api_key to ~/.config/claudio/secrets.json, then run claudio set mouth elevenlabs again so claudio reloads it. If you exported ELEVENLABS_API_KEY, restart claudio from that shell.

The claude process exited. claudio restarts it, and the brain says it is back and asks you to repeat yourself if you were mid-request.

If it keeps happening, the reason is at the end of brain.log:

tail -n 20 ~/.config/claudio/brain.log

Then check that Claude Code works and is signed in, outside claudio:

claude -p "say hi"

claudio tried to resume the last conversation, and claude could not resume it. claudio drops it and starts a fresh brain. Nothing to fix. Earlier days stay in the transcripts.

Switch the style: claudio set style brief for one sentence a reply, plain for the persona as written. For lasting changes, edit the persona.

Check, in order:

1. The hooks are not installed. claudio doctor shows it. Run claudio install.
2. The session started before the hooks. A session loads its hooks when it starts. Restart it.
3. It is not on your sessions platform. claudio only hears from sessions on the platform backend names: cmux panes, or bb threads.
4. It isn't a Claude Code session. Finished turns come from Claude Code hooks, so a session running another agent doesn't report them.
5. You did not hand it the work. With narrate set to handed-off, the default, only finishes of work the brain handed over in the last 30 minutes are narrated. claudio set narrate all narrates every finish.
6. You are muted, or narrate is none. Say “slash unmute”, or run claudio set narrate handed-off.

Ask “slash status” to hear which orchestrator is set. Change it by saying “the orchestrator is Core now”, or from the shell:

claudio set orchestrator Core

A change from the shell reaches the brain at its next restart, so tell it, or restart claudio. A .claudio.json in the project may also be setting orchestrator, and it wins over claudio set.

Check, in order:

1. You are muted, or narrate is none. Say “slash unmute”, or run claudio set narrate handed-off.
2. claudio was already asking you something. Each prompt is read out once. When claudio is already asking you something, it reads the new one out but leaves you to answer it in the session.
3. backend names the other platform. claudio reads out sessions only on the platform backend names. To switch, run claudio set backend bb (or cmux) and restart claudio; the bb plugin sets bb for the claudio it starts.

Then, on your platform:

• cmux: prompts and questions come from the Claude Code hooks, so check them as for a session that never reports back.
• bb: CLAUDIO_BACKEND=bb claudio doctor checks that bb is reachable. Without the plugin, claudio checks bb every 3 seconds, so a prompt can take that long.

Check, in order:

1. claudio isn't started. Click the sun in the panel's header to start it. claudio never restarts on its own: after /exit or a crash it stays off until you click. If the plugin's command setting is empty, the click starts nothing: start claudio yourself, in a terminal.
2. The panel is missing or stale. Reload bb's window with ⌘+R, after installing or updating the plugin.
3. claudio exits at start. Read ~/.config/claudio/bb.log, where the claudio the plugin started writes its screen, and follow the plugin's own log with bb plugin logs claudio -f.
4. Another claudio is running. Run one claudio at a time: one in a terminal and the plugin's would fight over the mic and the sockets. Quit the terminal one, then click the sun.

bb covers the plugin and its command setting.

A setting has a bad value. It is skipped, and the value before it is kept. The warning starts with where the value came from: the path of config.json, .claudio.json, or environment. Fix it there. claudio set refuses the same values with the same reason, and saves nothing.

claudio has no Deepgram key, so it cannot listen. Run claudio setup, or export the key before you start claudio:

export DEEPGRAM_API_KEY=your_deepgram_key

Deepgram rejected the key during setup. Copy a working key from console.deepgram.com and try again. After three refusals, setup stops with no working Deepgram key; setup stopped.

~/.claude/settings.json is not valid JSON, is not a JSON object, or its hooks section is not shaped the way Claude Code writes it. Nothing was changed. Fix the file, then run:

claudio install