In this tutorial, we install Echo on your Mac and hear it speak. By the end, a background service on this machine will speak any JSON message sent to localhost:3246.
Turn the volume up before the last step. You should hear the words "Hello from Echo."
A macOS LaunchAgent named com.echo that:
- Speaks JSON POSTed to
localhost:3246/notify - Starts when you log in
- Can stay silent when you mute it
We prove it with curl. Wiring Claude Code, Pi, or another host comes after you have heard the smoke.
You need:
- A Mac. Echo installs as a LaunchAgent.
- Bun. Install it with
curl -fsSL https://bun.sh/install | bash. - Node.js, for
npx. Any current version works.
You do not need git or a copy of the repository.
Check Bun:
bun --versionYou should see a version number, for example 1.2.4.
npx agent-echo install --adapter noneThis copies Echo to ~/Library/Application Support/echo/source, registers the LaunchAgent com.echo and starts it. The output should end with:
OK echo is healthy on :3246
If you see Voice server did not respond. Check logs: ~/Library/Logs/echo.log, open that log. The last few lines say what failed. Fix the cause and rerun the same install command. Running it again is safe.
For installation from a clone, see How to install Echo.
curl -fsS http://localhost:3246/healthYou should see JSON that starts like this:
{"status":"healthy","port":3246,...}Volume up. Then:
curl -X POST http://localhost:3246/notify \
-H 'Content-Type: application/json' \
-d '{"message":"Hello from Echo"}'Omitting voice_id resolves as identity-default. That is voices.json identity, edge en-GB-RyanNeural, not the provider defaultVoice (Ava). You should hear that identity voice say "Hello from Echo" (if edge-tts is installed for /opt/homebrew/bin/python3) and see:
{"status":"accepted","message":"Notification queued","request_id":"..."}HTTP 202 means the daemon accepted the line. Your ear is the check that it spoke. Anything on this machine can now speak by POSTing to localhost:3246/notify.
curl -X POST http://localhost:3246/notify \
-H 'Content-Type: application/json' \
-d '{"message":"Themis here. Ready to coordinate.","voice_id":"themis"}'You should hear a different voice. Themis maps to edge en-US-MichelleNeural. When you omit voice_id, Echo uses the identity mapping from step 3 (identity-default). There is no atlas agent key.
Work through these checks in order.
-
Confirm the daemon is running:
npx agent-echo status
You should see
running on :3246in theDaemonrow with aloadedmarker. See Status for the dashboard fields and offline behavior. If it saysnot running, rerunnpx agent-echo install --adapter none. If the installer refuses because port 3246 is occupied but not answering, runnpx agent-echo doctor. It names each degraded check and the command that fixes it. -
Check the daemon log:
tail -20 ~/Library/Logs/echo.log -
Ask Echo why it chose the voice it did. Every spoken notification appends one line to the voice-resolution log:
tail -3 ~/Library/Logs/echo/voice-resolution.jsonlYou should see JSON with a
providerfield and anattemptsarray.
Wrong voice on the no-voice_id smoke? Check 3 should show "resolution":"identity-default" and "voice":"en-GB-RyanNeural". Ryan is a British male. That is the identity voice, not a fallback.
If "resolution" is fallback and the voice is en-US-AvaNeural, that is the edge provider defaultVoice, not identity. The smoke omitted voice_id, so that is the wrong path.
If you hear macOS say ("Daniel") instead of Ryan, Echo fell back to the built-in macOS voice. Read the latest attempts[]. Edge is skipped only when it is disabled or its circuit breaker is open. Otherwise a failed Edge attempt means real synthesis failed. A common cause is that edge-tts is not installed for Homebrew Python at /opt/homebrew/bin/python3:
/opt/homebrew/bin/python3 -m pip install edge-ttsIf /opt/homebrew/bin/python3 does not exist, install Python first with brew install python, then rerun the command above. Restart Echo and repeat step 3. You should now hear Ryan (en-GB-RyanNeural).
No sound, but the curl returned "status":"accepted"? Check the output device and the volume, then the resolution log in check 3. If the last line has "success":false, the attempts array tells you which provider failed.
Echo is optional. If someone is in the room:
npx agent-echo mute onYou should see Mute: ON and Targets: speaker, microphone. Send the same "Hello from Echo"
request again. You should still get "status":"accepted", and you should hear nothing. Then:
npx agent-echo mute offThat prints Mute: OFF. Mute is machine-wide. It does not stop Oh My Pi live chat. Layers and
states: What Echo does.
One command fetches the newest release and reloads the service:
npx agent-echo@latest updateSee Update for settings preservation and recovery details.
You installed Echo as a self-starting macOS service, confirmed /health, heard "Hello from Echo", picked a persona, and proved that runtime mute turns the audio off without rejecting the request.
- Wire a supported host so it speaks on its own. How to install Echo
- Hear a waiting agent from across the desk on hosts with needs-input support. Set
ECHO_PREFERRED_NAMEif you want the line to start with your name. When an agent needs you - After wiring Claude Code, Pi, or omp, give this project a persona with
/echo-voice [name] [voice]inside the repo. Voices - Pick voices by ear in voices.md
- Start, stop, restart, and mute vs daemon disable in operations.md
- Look up
/notifyin http-api.md
Want an agent to ask you a question out loud and hear your answer? That is voice ask, Echo's speech-to-text feature: one spoken question, one spoken reply, transcribed on your Mac and returned to the agent. It is opt-in and needs sox (rec) and a local transcriber. The first ask needs macOS microphone permission, and on the measured Pi and omp path the prompt names your terminal application, not Echo. Set it up with Voice ask (speech-to-text).