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.

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 @mouadja/murmur

That pulls the published package from npm, runs the pre-launch banner, and spins up the overlay. On the first run it will also prompt you to fetch whisper.cpp:

# Windows: downloads whisper-cli.exe + ggml-base.en.bin into ./bin/whisper/
npx @mouadja/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 @mouadja/murmur setup:whisper

Option B — install globally

npm install -g @mouadja/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.

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. Version-controllable, shareable.
• 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, …).
• 100 % local — 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 %APPDATA%\murmur\config.json atomically and hot-reloads in the running app — no restart needed.

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.

LLM providers

Pick one. The openai-compat provider covers practically every local server that speaks the OpenAI chat-completions dialect.

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

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

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).

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
}

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.