murmur

npm install -g murmur-radio && murmur

A companion radio — "a whole radio station, for an audience of one," with an agent for a brain.

https://github.com/user-attachments/assets/59a300a8-8d61-443f-b592-8677e12e2be4

murmur is always on the air. It picks a topic and talks, plays a song, comes back and keeps going — whether or not you say anything. Type back and it answers out loud, chats for a bit, then eases back into the program.

What it's like

• It never goes quiet. Talk and music take turns on their own, with a good morning and a good night at the right hours. Leave it running in the background all day.
• Talk back, or don't. Type a line and the host answers in a voice that sounds like a person. Stay quiet and the show goes on.
• One host, and it gets to know you. A few questions on the first run give you a host whose character holds still. What grows is what it knows about you — your taste, your days, what you talked about last week.
• Everything is a file you can open. The host's character and the rules it picks songs by are plain text under ~/.murmur/. Change the music rules mid-song and the next pick follows them.

Get started

You need:

• Node.js 22.16+ or 24+
• Claude Code, logged in with your subscription — the brain is your own Claude session, so there is no API key to manage.
• A free fish.audio API key for the voice. You don't need it up front: the first run walks you through signing up and pasting it in.

npm install -g murmur-radio
murmur

The first run is a short conversation. It asks a few questions to shape your host, then offers to set up whatever is missing — the voice key, ffmpeg + yt-dlp for music, bun for the full-screen UI, and, if your Node comes from nvm, fnm, asdf or mise, a small ~/.local/bin/murmur shim so the command doesn't vanish when a project switches Node. Say no and it plays anyway, just with less: talk-only without the music tools, lines on screen instead of spoken without a voice. murmur --setup reopens that conversation any time.

Using it

• Commands. In the full-screen UI, / lists what it takes: settings, the setup guide, a bug report, a wish, /update (installs a newer murmur from npm) and /quit. The plain front-end takes the same commands typed in full; Ctrl-C says goodbye too.
• What it plays is yours to steer. Write your own notes in ~/.murmur/music-policy.md — more Cantonese, no covers, a decade to live in — and they are added to murmur's built-in song-picking rules before every pick, winning wherever the two disagree. Empty the file to go back to the built-in rules alone.
• When something goes wrong, /bug turns what just happened into a filled-in GitHub report with the log attached. A run that dies without saying goodnight is noticed on the next start and offered up the same way. Logs live in ~/.murmur/log/, one file per day, two weeks kept.
• Flags worth knowing: --plain (skip the full-screen UI), --no-music, --persona PATH, --version. Pacing, cadence and the rest are the option table at the top of src/config.ts.

How it works

A Node.js (TypeScript) engine runs the program and mixes the audio; a front-end draws the screen and reads your keyboard. While one segment plays, the next is already being prepared, so there is no dead air. A song ducks under the host's voice instead of stopping.

murmur ships no model. Three things come off the network: the brain is your Claude session (via @anthropic-ai/claude-agent-sdk), the voice is fish-speech over fish.audio's hosted API, and the music streams in through yt-dlp. Everything murmur owns — the program logic, memory, persona and audio mixing — runs on your machine.

The components and the reasons behind them: docs/architecture.md. The full design: specs/DESIGN.md.

Status

Every code spec is built. What remains is acceptance by ear — pacing over a real day, how the steering feels — plus a handful of engineering debts. Current focus: specs/STATUS.md; what comes next: ROADMAP.md; engineering notes with the numbers measured along the way: docs/blog/.

Development

Running from a checkout needs Node 24+ (it runs the TypeScript directly) and pnpm (corepack enable pnpm). One command sets up and runs the app; a second terminal tails a live debug log:

make dev      # sync deps, report what is missing, launch the app either way
make logs     # in another terminal: tail diagnostics + memory while it runs

make dev runs the real brain + music with the hosted voice (VOICE=hosted, endpoint loaded from the gitignored .env — make dev-fishaudio selects the fish.audio config); pass VOICE=stub for a silent voice, or STUB=1 make dev for a fully offline session (canned brain, no music — needs no network/binaries). The program timeline mirrors to .dev/dev.log; make logs (scripts/devwatch.ts) tails that and folds in a periodic memory-tree line. make help lists every target.

Under the hood:

pnpm install
node src/main.ts               # run from source
node src/main.ts --brain stub --voice stub --no-music --no-bed   # fully offline
pnpm test                      # fast unit layer (vitest; fakes, no network)
pnpm run typecheck             # tsc over src/, test/ + the tooling scripts
pnpm run lint                  # oxlint
brew install ffmpeg yt-dlp    # binaries real runs need (music)

Testing is layered (see DESIGN.md §11): unit tests are test-first against fakes; real-boundary checks run on demand as throwaway scratch/ smokes; sensory "sounds human / feels like radio" checks are human acceptance. Every seam ships a fake, so the core loop is testable without real audio, LLM, or network.

Conventions: specs are written in English and optimized for a coding agent to consume. No CJK anywhere in source (comments, literals, docstrings) — the radio speaks whatever language the listener settled on at onboarding (the machine's locale by default, English as the floor), produced by the model from the persona; enforced by scripts/check-source-language.ts via pre-commit.

Credits

The voice is fish-speech by @fishaudio — the reason murmur sounds like a person on the radio instead of a screen reader. murmur talks to it through fish.audio's hosted API; the model and the work behind it are theirs.

License

murmur's own code is MIT — see LICENSE.

Third-party services. murmur ships no model weights; it calls services that carry their own terms, and complying with them is yours:

• Brain — your own Claude session, under your own Anthropic subscription.
• Voice — fish.audio, the endpoint the first run sets up, serves fish-speech, whose model carries the Fish Audio Research License (research and non-commercial use free; commercial use by separate license). Whoever operates the endpoint you point at may add service terms of their own — read both; murmur is not a party to either.
• Music — retrieval runs through yt-dlp on your machine, against whatever source you point it at.

And these, only on the paths that need them:

• A package registry — a packaged first boot runs bun install for the TUI; without it murmur falls back to the plain front-end.
• raw.githubusercontent.com — downloading a built-in voice preset's reference clip (cached and hash-pinned after the first fetch).
• registry.npmjs.org — the version check behind /update.