Getting started
Install claudio, answer the setup questions, and check everything with the doctor.
Install claudio, answer a few setup questions, and run the doctor to confirm every part works. Check what you need first, and pick where your sessions live: the backend setting, cmux by default or bb. Anything specific to your platform is on its page: bb or cmux.
Install claudio
uv tool install git+https://github.com/ActurialCapital/claudioThis puts a claudio command on your path.
Choose where your sessions live
For bb threads, set the backend, then run setup yourself (setting it counts as a first run, so claudio alone would skip setup):
claudio set backend bb
claudio setupFor cmux panes, skip this: cmux is the default. Platforms compares the two.
Run it from a project
cd ~/code/myproject
claudioThe brain runs in the directory you start claudio from and reads files there when a question needs facts. A .claudio.json in that directory can override settings for that project.
Answer the setup questions
The first run starts a short setup. It checks that claude is installed, and the sessions' platform that backend names, marking each with ✓ or ✗, then asks for:
- Your Deepgram key: tested against Deepgram before it's saved. You get three tries
- The orchestrator: the session that gets your tasks by default, picked by number from the ones the platform has open: cmux's workspaces or bb's threads. If none is listed, you type its title
- A voice: one of six Aura-2 voices. Any other Aura-2 voice works later with
claudio set voice - The brain's model and effort: press Enter to keep
defaultandlow - The transcript layout:
inline, orsplitwith your turns on the right - Barge-in: whether talking over claudio pauses it
Settings go to ~/.config/claudio/config.json and the key to secrets.json beside it, readable only by you. Run claudio setup to answer the questions again.
Install the hooks
Setup then offers to add three hooks to ~/.claude/settings.json: Stop, Notification, and PreToolUse for AskUserQuestion. Your sessions use them to report back, so answer yes.
Your other settings stay as they are, and the previous file is copied to settings.json.bak-claudio first. If settings.json is a symlink, the file it points to is the one updated. If the file isn't valid JSON, claudio changes nothing and tells you why.
Add or remove the hooks any time with claudio install and claudio uninstall.
A Claude Code session loads its hooks when it starts. Restart any session that was already running, or it won't report back.
Check everything
claudio doctorThe doctor checks each part in this order. The two lines after the version are for the platform backend names; these are cmux's, and with bb they read bb reachable and orchestrator '…' is a bb thread:
A failed check shows ✗ and a hint beside it. Troubleshooting covers each one.
The doctor then runs one typed turn through the brain and the mouth, and you hear "the doctor is in." It finishes with all good, or fix the ✗ lines above.
Have your first conversation
Run claudio again. On the first start it builds the echo canceller, once, if the Xcode command line tools are installed. It then prints its banner, and the state line reads warming up the brain…, then listening.
Ask a question about the project, then ask for some work and watch the orchestrator pick it up:
Press Enter to cut a reply and Ctrl+C to quit. To see and type to claudio in bb's panel instead of a terminal, install the bb plugin. Next, learn how to talk to it.