JSPM

What is Murmur?

Murmur is a tiny floating button that sits on top of your desktop. You tap it and talk, and a few seconds later a clean, structured prompt appears exactly where your cursor is — in Cursor, ChatGPT, a terminal, a GitHub issue, anywhere.

Under the hood, your voice is transcribed on your own machine (with whisper.cpp), then rewritten into a high-quality prompt by your own local LLM (Ollama, LM Studio, llama.cpp server — your choice). Nothing ever leaves your computer unless you explicitly configure a cloud endpoint.

Think of it as:

"I know what I want, I just don't want to type it."

See it in 30 seconds

1. A small pill floats on your desktop. Always on top. Drag it anywhere.
2. Click it (or hold Ctrl+Shift+Space) and talk. A soundbar reacts while you speak.
3. Release. The pill walks through recording → transcribing → refining → injecting → done.
4. The refined prompt appears at your cursor. Your original clipboard is restored a moment later.

You stay in flow. No context switch. No "open app, paste, reformat, paste again."

Get started

You need Node.js 20+, a working microphone, and a local LLM server running somewhere (see the table further down if you're not sure which). Windows 10/11, macOS 12+, and modern Linux (X11; Wayland via Xwayland) are all supported.

Option A — just try it (no clone, ~15 s)

npx @mouadja02/murmur

That pulls the published package from npm, runs the pre-launch banner, and spins up the overlay.

On the first run, Murmur detects your OS and walks you through setup interactively. It first asks for your LLM connection:

── LLM setup ─────────────────────────────────────────────

    ? LLM_PROVIDER (ollama | openai-compat | anthropic)
    ? LLM_BASE_URL (suggested: http://localhost:11434)
    ? LLM_MODEL (example: qwen3:4b)

If LLM_PROVIDER, LLM_BASE_URL, or LLM_MODEL already exist in your environment or .env, Murmur shows them as defaults. Press Enter to keep using the env value without writing over it in config.json. If no env value exists, Murmur requires an explicit answer so you do not accidentally launch against the wrong model.

If whisper-cli and/or the model file are missing, it asks:

── First-time setup ────────────────────────────────────────

  o whisper-cli not found at /home/you/.config/murmur/whisper-cli
    ? Install whisper.cpp now? (builds from source, ~2-5 min) (Y/n)

  o whisper model not found at /home/you/.config/murmur/models/ggml-base.en.bin
    ? Download ggml-base.en.bin (~148 MB)? (Y/n)

Say yes and Murmur does the rest — building whisper.cpp from source on Linux/macOS (or downloading a prebuilt binary on Windows), downloading the model, and writing the correct paths into your config file. No manual setup script, no editing JSON.

If you prefer to run the setup step manually (e.g. on a CI agent):

# Windows: downloads whisper-cli.exe + ggml-base.en.bin into <userData>/bin/whisper/
npx @mouadja02/murmur setup:whisper

# macOS / Linux: downloads ggml-base.en.bin into ./models/
# and prints the exact command to install whisper-cli via your package manager
npx @mouadja02/murmur setup:whisper

Option B — install globally

npm install -g @mouadja02/murmur
murmur

After this, murmur is on your PATH and you can launch it from any terminal.

Option C — hack on the source

git clone https://github.com/mouadja02/murmur.git
cd murmur
pnpm install
pnpm setup:whisper
pnpm dev

All three options drop you in the same place. The first run creates a config file at %APPDATA%\murmur\config.json (Windows), ~/Library/Application Support/murmur/config.json (macOS), or ~/.config/murmur/config.json (Linux), with sensible defaults, and prints a banner in the terminal. Grab the control panel URL it shows (default http://localhost:7331) to tweak things in a browser without touching JSON.

Linux runtime deps. The overlay's global hotkeys + paste injection use uiohook-napi + @nut-tree-fork/nut-js, which link against X11 at runtime. On Ubuntu/Debian:

sudo apt-get install -y libx11-6 libxtst6 libxkbcommon0

Most desktops ship these by default; install them if the overlay fails to boot with an Error loading shared library message.

macOS accessibility permission. Synthetic key events (the Cmd+V paste step) require Murmur to be granted Accessibility access. On first run, macOS will prompt you automatically. If you dismissed the prompt, go to System Settings → Privacy & Security → Accessibility, find Electron (or Murmur), and toggle it on. Without this permission the overlay runs but the refined text will not be pasted at your cursor.

If you don't have a local LLM yet, the fastest path is:

# Install Ollama from https://ollama.com, then:
ollama pull qwen3:4b

Murmur targets qwen3:4b on Ollama by default.

How it works

Four stages, strictly local:

Every session gets a timestamped folder under logs/ with the WAV, the raw transcription, the exact prompt sent to the LLM, and the refined output — so you can debug anything after the fact.

Features at a glance

• One-click or push-to-talk — click the pill, or hold Ctrl+Shift+Space.
• Drag anywhere — pill position is saved and survives restart.
• Toggle hotkey — Ctrl+Shift+H hides / shows the overlay from any app.
• Right-click menu — open the control panel, reset position, quit.
• Control panel on localhost — browser-based UI for system prompt, skills, provider, hotkeys, and paths. Changes hot-reload without restarting.
• Skills as Markdown — drop .md files into ./skills/, toggle them on/off from the panel. Import directly from a local file or a raw URL. Version-controllable, shareable.
• CLI / env override badges — when a field is locked by a --flag or env var, the control panel marks it read-only with a clear badge and tooltip explaining exactly how to unlock it.
• Terminal pre-launch banner — every pnpm dev shows your current setup and offers a one-key menu to edit the prompt or jump to the panel.
• Provider agnostic — Ollama native API, any OpenAI-compatible server (LM Studio, llama.cpp server, vLLM, Jan, KoboldCpp, oobabooga, …), and Anthropic Claude.
• 100 % local by default — no telemetry, no outbound network calls except to the LLM server you configured.
• Session logs — every run writes audio + timings + prompts to logs/<timestamp>/ for full traceability.

The control panel

Open it from the overlay (right-click → Open control panel), from the pre-launch terminal menu, or by pasting http://localhost:7331 into your browser.

Every save writes back to the config file atomically and hot-reloads in the running app — no restart needed.

Auto-refresh and form protection. The panel polls /api/state every 4 seconds to keep the composed system prompt and skill list in sync. It will never overwrite a field you are actively editing — each form section tracks its own "dirty" state and auto-refresh skips it until you save.

Skills

Skills are small Markdown files that layer onto your base system prompt when enabled. Perfect for "always talk like a senior Go reviewer", "bias toward concise output", or project-specific vocabulary.

Each skill lives at skills/<id>.md:

---
id: concise-output
name: Concise output
description: Trim filler, keep the prompt to the point.
---

Prefer terse, structured prompts. Use bullets for constraints.
No hedging, no apologies, no restating the question.

You can author them in your editor (they're git-friendly) or in the control panel's Skills tab. Enabled skills are concatenated under an ## Active skills header in the prompt sent to the LLM.

Importing skills

The Skills tab has an ↑ Import button that opens an import panel with two tabs:

• From file — click to browse or drag-and-drop any .md file onto the drop zone. Parses YAML frontmatter (id, name, description) and body, then pre-fills the new-skill form.
• From URL — paste any raw Markdown URL (e.g. a GitHub raw link or Gist) and click Fetch. Works with any public .md file.

Both paths land in the new-skill form where you can review and adjust before saving.

LLM providers

Pick one. The openai-compat provider covers practically every local server that speaks the OpenAI chat-completions dialect — and also cloud endpoints like OpenAI and OpenRouter.

openai-compat expects the full base URL including /v1 — Murmur will not append it for you.

anthropic also expects /v1 in the base URL (https://api.anthropic.com/v1).

⚠️ Online provider data notice. When baseUrl points to a hostname (not localhost or an IP address), the control panel shows a warning banner after you save. Cloud providers receive your voice transcription text and refined prompts. Review each provider's privacy and data-retention policy before use. We recommend a local model for any sensitive or proprietary work — see the Model guide below.

Quick recipes

# Ollama (default)
ollama pull qwen3:4b
pnpm dev

# LM Studio — load a model, click "Start Server"
pnpm dev --provider openai-compat --base-url http://localhost:1234/v1 --model qwen/qwen3-1.7b

# llama.cpp server
# llama-server -m models/qwen3-4b.Q4_K_M.gguf --port 8080
pnpm dev --provider openai-compat --base-url http://localhost:8080/v1 --model qwen3

# Generic, with an API key
pnpm dev --provider openai-compat --base-url http://localhost:5000/v1 --model my-model --api-key sk-xxx

# OpenAI (online ☁)
pnpm dev --provider openai-compat --base-url https://api.openai.com/v1 --model gpt-4o-mini --api-key sk-...

# Anthropic Claude (online ☁)
pnpm dev --provider anthropic --base-url https://api.anthropic.com/v1 --model claude-haiku-4-5 --api-key sk-ant-...

# OpenRouter (online ☁ — free models available)
pnpm dev --provider openai-compat --base-url https://openrouter.ai/api/v1 --model meta-llama/llama-3.1-8b-instruct:free --api-key sk-or-...

# Groq (online ☁ — very fast inference)
pnpm dev --provider openai-compat --base-url https://api.groq.com/openai/v1 --model llama-3.1-8b-instant --api-key gsk_...

Overlay cheatsheet

From the terminal

After Murmur finishes bootstrapping it prints a compact status block in the terminal with clickable links (thanks to OSC-8 hyperlinks — works in Windows Terminal, iTerm2, VS Code, Alacritty, WezTerm, Kitty and most modern emulators):

  o murmur is ready
    Overlay   show / hide / toggle
    Panel     http://localhost:7331
    Hotkeys   Ctrl+Shift+Space (push-to-talk) / Ctrl+Shift+H (toggle)

• Overlay links use Murmur's custom murmur://show, murmur://hide, murmur://toggle URL scheme. Clicking them (Ctrl-click in some terminals) routes the action straight into the already-running Murmur instance via Electron's single-instance lock — no browser tab opens. Registration happens automatically the first time Murmur starts; on Linux a .desktop file is written to ~/.local/share/applications/.
• Panel link is a regular http:// URL and opens the control panel in your default browser.

The same overlay controls live in the Overlay widget at the top-right of the browser panel, with a live status pill (visible / hidden).

Config precedence

Settings are resolved in this order, highest to lowest:

CLI flags  >  environment variables  >  config file  >  built-in defaults

This means a --model flag or LLM_MODEL env var will always win over whatever is saved in config.json. Saving from the control panel writes to the config file, but the change appears to revert if a higher-precedence source is active.

The control panel makes this explicit. Any field whose current value comes from a CLI flag or env var is rendered read-only with a coloured badge beneath it:

Locked by --model CLI flag

Hovering the badge shows a tooltip: "Restart Murmur without the --model flag to edit this here."

To unlock a field: remove the corresponding entry from your .env file or drop the flag from the pnpm dev command.

Session logs

Every invocation writes to logs/<ISO-timestamp>/:

logs/2026-04-17T19-28-01-234Z/
├── audio.wav             # exactly what Whisper received
├── transcription.txt     # Whisper's raw output
├── system-prompt.txt     # base + enabled skills, as sent
├── refined.txt           # what got pasted
├── whisper-stderr.log
└── timings.json          # audioDurationMs, transcribeMs, refineMs, injectMs, totalMs

timings.json is your ground truth for end-to-end latency — see Latency below.

Power-user reference

pnpm dev --provider openai-compat --base-url http://localhost:1234/v1 --model qwen/qwen3-1.7b

{
  "provider": "ollama",
  "baseUrl": "http://localhost:11434",
  "model": "qwen3:4b",
  "apiKey": null,
  "temperature": 0.2,
  "whisperCliPath": "whisper-cli",
  "whisperModelPath": "./models/ggml-base.en.bin",
  "sampleRate": 16000,
  "hotkeyCombo": "Ctrl+Shift+Space",
  "toggleHotkeyCombo": "Ctrl+Shift+H",
  "clipboardRestoreDelayMs": 150,
  "overlay": {
    "anchor": "bottom-center",
    "offsetX": 0,
    "offsetY": 24,
    "position": null
  },
  "logsDir": "./logs",
  "skillsDir": "./skills",
  "systemPrompt": "You refine a raw voice transcription …",
  "enabledSkills": [],
  "controlPanelPort": 7331
}

Model guide

Choose a model that fits your hardware. All local tiers use Ollama — install from ollama.com, then ollama pull <model> and set the model name in the control panel's Provider tab.

Not sure what tier you are?

• RAM: Windows → Task Manager → Performance → Memory. macOS → About This Mac. Linux → free -h
• GPU VRAM: Windows → Task Manager → GPU. macOS → About This Mac → Graphics. Linux → nvidia-smi
• Rule of thumb: the model file must fit in VRAM (GPU inference) or RAM (CPU inference). Leave ~2 GB headroom for the OS.

The interactive Model guide tab in the control panel (http://localhost:7331#model-guide) shows the same table with one-click ollama pull copy commands.

Privacy note for online providers

When baseUrl is a domain hostname (not localhost or a bare IP), Murmur shows a warning banner in the control panel after you save. Cloud providers process your data under their own terms:

• OpenAI privacy policy
• Anthropic privacy policy
• OpenRouter privacy policy
• Groq privacy policy

For production or privacy-sensitive use, run a local model. The warning does not appear for IP addresses or localhost — those could be your own private server.

Contributing

Scripts

CI

Every push and every PR to main runs the CI workflow (.github/workflows/ci.yml) on both Ubuntu and Windows:

1. pnpm install --frozen-lockfile
2. pnpm check (typecheck + lint)
3. pnpm build
4. pnpm test

A red check blocks merge. Keep it green.

Releases

Releases are driven by git tags. To cut a new version:

# 1. Bump the version in package.json
pnpm version patch        # or minor / major

# 2. Push the commit + tag
git push origin main --follow-tags

The Release workflow (.github/workflows/release.yml) then runs two jobs in sequence:

1. GitHub Release (Windows bundle) — checks out the tag, verifies package.json matches the tag, runs pnpm check + pnpm test:ci, builds, zips bin/ + dist/ + scripts/ + skills/ + docs/ + package.json + lockfile + README + LICENSE + logo into murmur-v<version>-win-x64.zip, and attaches it to an auto-generated GitHub Release.
2. npm publish — on an Ubuntu runner: re-installs, rebuilds, then runs pnpm publish --access public using the NPM_TOKEN secret. If the token isn't configured the job logs a warning and exits cleanly, so the GitHub Release still ships.

You can also trigger the workflow manually from the Actions tab with a tag input (useful for re-releases).

Setting up NPM_TOKEN (one-time)

1. Generate an Automation token on npmjs.com → Access Tokens with Publish scope (2FA-exempt).
2. Add it to the GitHub repo at Settings → Secrets and variables → Actions → New repository secret, name it NPM_TOKEN.
3. The next tagged push will publish both a GitHub Release and the npm package.

Files shipped to npm are whitelisted in package.json#files — run pnpm pack locally to inspect exactly what the tarball will contain before publishing.

Dependabot

.github/dependabot.yml opens weekly npm PRs (split into dev-dependencies and runtime-dependencies groups) and monthly github-actions PRs.

Known rough edges

1. No streaming anywhere. Each stage is strictly sequential. Streaming STT + streaming LLM + streaming injection is the biggest pending latency win.
2. Model cold-start dominates first-run latency. Pre-warming the model on app start (keep_alive) is queued.
3. Paste-based injection only, no per-target typing fallback.
4. No VAD / silence trimming. Trailing "uhh" and dead air get transcribed and fed to the LLM.
5. Renderer uses the deprecated ScriptProcessorNode. Move to AudioWorklet before any non-spike build.
6. No tray icon. Hide / show is handled by the toggle hotkey and the right-click context menu; restart re-shows the overlay if you ever lose the toggle binding. A tray fallback is queued.
7. Off-screen drag is auto-clamped on relaunch. The saved free position is clamped to the nearest connected display's work area on launch, so a saved position from a now-disconnected monitor doesn't strand the overlay.
8. Single utterance at a time. Concurrent recordings are dropped; queueing is not implemented.

License

MIT © Mouad Ja. Pre-1.0; APIs and config may still change.