openwhispr-mcp-setup
Skill4 starsChanged 4 months agoMITView on GitHub
Stand up the `openwhispr` voice-notes MCP on a new machine and wire it into both Claude clients — the OpenWhispr add-on alongside mcp-bridge-setup (like whatsapp-mcp-setup). It exposes the external OpenWhispr desktop app's local transcript store (a SQLite DB + `.webm` recordings under `~/Library/Application Support/open-whispr/`) as a stdio MCP, fronted by a supergateway + launchd bridge on $OPENWHISPR_BRIDGE_PORT/:8002 for Claude Code and a direct stdio command for Cowork, and owns the watermark that makes voice ingestion idempotent. Use when setting up OpenWhispr/voice on a new machine, when Cowork or Code can't see the `openwhispr` server, when the openwhispr bridge (:8002) is down, when the voice ingest loop can't find notes, or when list_transcripts is stuck on fixtures instead of the real store.
- Reads credentials
- Installs packages
- Sends data out
In this repository17 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- add-an-addonSkill
- backup-recoverySkill
- body-mcp-setupSkill
- cos-setupSkill
- cos-upgradeSkill
- debug-cowork-mcp-issuesSkill
- fitness-mcp-setupSkill
- guard-setupSkill
- hub-handoverSkill
- mcp-bridge-setupSkill
- nutrition-mcp-setupSkill
- setup-vaultSkill
- spoke-setupSkill
- voice-operationsSkill
- whatsapp-mcp-setupSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 64
Run the loader preamble as the first line of every shell block below — it exports $REPO_ROOT, $NODE_BIN, $BREW_PREFIX, $SUPERGATEWAY_BIN, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OpenWhispr MCP setup (voice-notes add-on — stdio MCP bridge :8002)
Why this exists / architecture
openwhispr is the optional voice add-on. Unlike the core Cos servers (board, calendar,
guard, vault), it has an external-app dependency: it does nothing but expose the
OpenWhispr desktop app's local transcript store, so it only makes
sense on a machine where you actually use OpenWhispr. That's why it lives in its own skill — the
same shape as whatsapp-mcp-setup (which integrates an external app + needs pairing). board /
calendar / guard / vault stay in mcp-bridge-setup; this skill adds the one optional voice
server on top.
It is a single process — mcp/openwhispr-server/server.mjs, a Node stdio MCP server — and
it registers into Cos the same two ways the core servers do:
- Claude Code reaches it over HTTP via a supergateway + launchd BRIDGE on
:8002($OPENWHISPR_BRIDGE_PORT, labelcom.chiefofstaff.mcp-openwhispr, IN.mcp.json). - Claude Cowork Desktop spawns it as a direct stdio
commandentry inclaude_desktop_config.json— identical to how mcp-bridge-setup wires board/calendar/etc.
Claude Code ──HTTP──> localhost:8002/mcp ──supergateway(launchd)──> node openwhispr-server (stdio)
│ reads READ-ONLY (sqlite3 CLI)
└──> ~/Library/Application Support/open-whispr/
transcriptions.db + audio/*.webm
Cowork Desktop ──spawns stdio directly──────────────────────────────────> node openwhispr-server (§4)The server reads the store read-only (via the sqlite3 CLI; WAL lets it read safely alongside a
running OpenWhispr — though a clean shutdown can transiently remove the -shm file a read-only open
needs, see Gotchas) and owns the watermark (state/watermark.json) that
makes the voice ingest loop idempotent — list_transcripts → route → mark_processed never
re-emits a routed note. The board-side routing is owned by /second-brain-ingest + the voice
recipe; this skill only stands up the plumbing.
This add-on's one process (alongside mcp-bridge-setup's four core servers + two sidecars):
| process | what runs | env | bridge port | launchd label | in .mcp.json? |
| openwhispr (MCP bridge) | node mcp/openwhispr-server/server.mjs via supergateway | OPENWHISPR_DB + OPENWHISPR_AUDIO_DIR (the real store) | 8002 | com.chiefofstaff.mcp-openwhispr | yes (http://localhost:8002/mcp) |
Tools (4): list_transcripts (unprocessed-by-default, watermark-filtered), get_transcript
(full text + audio_path metadata), get_watermark, mark_processed (advances the watermark —
the idempotency primitive). See mcp/openwhispr-server/README.md for the full contract.
Machine config comes from the loader (run the preamble in §1): it exports
$REPO_ROOT,$BREW_PREFIX,$NODE_BIN,$SUPERGATEWAY_BIN,$LAUNCH_AGENTS_DIR,$COWORK_CONFIG,$OPENWHISPR_DB,$OPENWHISPR_AUDIO_DIR, and$OPENWHISPR_BRIDGE_PORT(=8002) /$OPENWHISPR_BRIDGE_URL(=http://localhost:8002) — use those instead of hardcoding paths, the Homebrew prefix, your username, or the port.
Prerequisites
- Node + npm (Homebrew) and the server's deps:
(cd mcp/openwhispr-server && npm i). supergateway(npm install -g supergateway) — the stdio→HTTP bridge for Claude Code, exactly as in mcp-bridge-setup.- The OpenWhispr desktop app installed, with at least one recorded note — this is the external
dependency (the analog of whatsapp's phone pairing / guard's HuggingFace login). Without it there
is no
transcriptions.dbto read; you can still wire everything against the bundled fixtures for a dry run (§1), but production needs the real store.
Run the loader preamble as the first line of every shell block below — it exports $REPO_ROOT,
$NODE_BIN, $BREW_PREFIX, $SUPERGATEWAY_BIN, $LAUNCH_AGENTS_DIR, $COWORK_CONFIG,
$OPENWHISPR_DB, $OPENWHISPR_AUDIO_DIR, the bridge port/URL, etc., so nothing below is
hardcoded. $U=$(id -u) is derived inline where launchctl needs it.
source "$(git rev-parse --show-toplevel)/config/load-config.sh"Steps
1. Confirm the OpenWhispr store (the external dependency)
The server reads OpenWhispr's Electron userData dir — transcriptions.db (transcript text) +
audio/*.webm (recordings, mapped to each note by the trailing -<id>). Check it exists:
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
[ -f "$OPENWHISPR_DB" ] && echo "OpenWhispr store found: $OPENWHISPR_DB" \
|| echo "No store at $OPENWHISPR_DB — install OpenWhispr + record a note, or use fixtures (below)"
ls -d "$OPENWHISPR_AUDIO_DIR" 2>/dev/null && echo "audio dir OK"- No store yet? Either install OpenWhispr and record one note, or wire everything against the
bundled fixtures for a dry run by setting
OPENWHISPR_FIXTURES="$REPO_ROOT/mcp/openwhispr-server/fixtures"in §2–4 instead ofOPENWHISPR_DB— but never leaveOPENWHISPR_FIXTURESset in the real plist/Cowork config (that's the classic "stuck on fixtures" bug — see Gotchas). - CHECKPOINT —
$OPENWHISPR_DBexists (or you've consciously chosen the fixtures path).
2. Verify the stdio server runs
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
(cd "$REPO_ROOT/mcp/openwhispr-server" && npm i >/dev/null 2>&1)
OPENWHISPR_DB="$OPENWHISPR_DB" OPENWHISPR_AUDIO_DIR="$OPENWHISPR_AUDIO_DIR" \
"$NODE_BIN" "$REPO_ROOT/mcp/openwhispr-server/server.mjs" # Ctrl-C; prints "openwhispr MCP server ready (tools: …)"- CHECKPOINT — the ready line prints the four tool names. (To prove it sees the real store,
§6's
list_transcriptswill reportSource: sqlite.)
3. Install the launchd BRIDGE (:8002)
The plist is generated from mcp/openwhispr-server/openwhispr.service.json by
scripts/gen-launchd.mjs (see mcp/CLAUDE.md) — it renders the :8002 supergateway bridge with
env OPENWHISPR_DB + OPENWHISPR_AUDIO_DIR (the real voice store), the idle-exit opt-in, and
PATH led by $BREW_PREFIX/bin, then bootout→bootstrap→kickstart in one step on macOS. Name
openwhispr explicitly so it installs only this add-on's plist (a bare --install would render just
the core services):
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
mkdir -p "$REPO_ROOT/mcp/logs"
node "$REPO_ROOT/scripts/gen-launchd.mjs" --install openwhispr- CHECKPOINT — an MCP
initializeon:8002returnsserverInfo.name == "openwhispr":source "$(git rev-parse --show-toplevel)/config/load-config.sh" curl -s -X POST "$OPENWHISPR_BRIDGE_URL/mcp" \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \ | grep -o '"name":"openwhispr"' && echo "openwhispr bridge OK"
4. Register BOTH clients (each registers differently!)
As in mcp-bridge-setup, the two clients register differently — getting this wrong is the usual failure.
Claude Code — HTTP via the bridge. .mcp.json is generated (CI-checked) from the manifest,
so don't hand-edit it — regenerate it and the openwhispr entry (http://localhost:8002/mcp, from
the descriptor's clients) lands alongside the core board/calendar/guard/vault entries:
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
node "$REPO_ROOT/scripts/gen-mcp-json.mjs"Claude Cowork Desktop — direct stdio. claude_desktop_config.json ($COWORK_CONFIG) accepts
stdio command servers only (an HTTP url is rejected — same validated rule as
mcp-bridge-setup §5). gen-cowork-config.mjs does a backup-first, additive merge — it preserves
the other servers + preferences and refreshes only the named openwhispr entry from the descriptor
(absolute $NODE_BIN, the real OPENWHISPR_DB/OPENWHISPR_AUDIO_DIR, never OPENWHISPR_FIXTURES):
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
node "$REPO_ROOT/scripts/gen-cowork-config.mjs" openwhispr- Quit + reopen Claude Desktop (⌘Q) — it reads this file only at launch; then
openwhisprappears in Cowork's tools. - CHECKPOINT — both registrations present:
source "$(git rev-parse --show-toplevel)/config/load-config.sh" grep -q '"openwhispr"' "$REPO_ROOT/.mcp.json" && echo ".mcp.json OK" "$NODE_BIN" -e 'const c=require(process.env.COWORK_CONFIG);process.exit(c.mcpServers&&c.mcpServers.openwhispr?0:1)' \ && echo "Cowork config OK"
5. Confirm mcp/ensure-bridges.sh picks it up (automatic — no edit)
ensure-bridges.sh is a thin consumer of the manifest: its service + probe list comes from
node mcp/service-manifest.mjs --probe-list, so the committed openwhispr.service.json descriptor
(probe: httpListen) is bootstrapped + probed with no edit to the script (see mcp/CLAUDE.md).
A machine without the add-on installed (no plist) is skipped silently; an installed-but-down one
WARNs.
- CHECKPOINT — the script bootstraps it and reports it up:
source "$(git rev-parse --show-toplevel)/config/load-config.sh" "$REPO_ROOT/mcp/ensure-bridges.sh" | grep -i openwhispr # expect: "[mcp] openwhispr up on :8002"
6. End-to-end verify (proves it reads the REAL store)
source "$(git rev-parse --show-toplevel)/config/load-config.sh"
curl -s -X POST "$OPENWHISPR_BRIDGE_URL/mcp" \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_transcripts","arguments":{"limit":3}}}'
# expect the result text to begin "Source: sqlite | watermark: …" — NOT "Source: fixtures"- CHECKPOINT —
list_transcriptsreturnsSource: sqlite(your live notes) and both clients seeopenwhisprafter a ⌘Q reopen. The voice ingest loop (list_transcripts → get_transcript → route to vault/board → mark_processed) is then exercised by/voice-operations(the reads + watermark) +/second-brain-ingest(the routing); this skill only proves the plumbing.
Manage
launchctl kickstart -k gui/$(id -u)/com.chiefofstaff.mcp-openwhispr # restart the bridge
launchctl bootout gui/$(id -u)/com.chiefofstaff.mcp-openwhispr # stop the bridge (e.g. on a machine without OpenWhispr)
tail -f mcp/logs/openwhispr.err.log # supergateway / server logRemove the add-on entirely (machine without OpenWhispr): launchctl bootout the agent, delete
~/Library/LaunchAgents/com.chiefofstaff.mcp-openwhispr.plist, and delete cfg.mcpServers.openwhispr
from the Cowork config by hand (gen-cowork-config openwhispr is additive — rerunning it would
re-add the entry, so don't). .mcp.json and ensure-bridges.sh are committed/manifest-driven, so
leave them as-is — once the plist is gone, ensure-bridges.sh skips the un-installed agent silently
and nothing answers on :8002.
Gotchas (read before editing)
- Never leave
OPENWHISPR_FIXTURESset in the real plist/Cowork config. It is the highest-precedence source and wins over the real DB — so a strayOPENWHISPR_FIXTURES(handy for a dry run in §1–2) silently serves the three bundled test notes instead of your voice notes. The tell:list_transcriptsreportsSource: fixturesinstead ofSource: sqlite. Production sets onlyOPENWHISPR_DB+OPENWHISPR_AUDIO_DIR. - The bridge reads the store directly — the OpenWhispr app need not be running. It uses the
sqlite3CLI read-only (WAL allows concurrent readers), and maps each transcript to its.webmby the trailing-<id>. OpenWhispr's own loopback "CLI bridge" (random port 8200–8219) exposes no read endpoint for audio and vanishes when the app quits, so this server never depends on it. (One caveat — next bullet — a clean OpenWhispr shutdown can transiently remove the WAL-shmfile a read-only open needs.) - WAL + read-only: a missing
-shmcan fail the open (SQLite error 14). A read-only open needs the WAL-shmshared-memory file, and a-readonlyconnection cannot create it — so after OpenWhispr does a clean shutdown (which checkpoints and removes-wal/-shm),list_transcriptscan fail withunable to open database file. It recovers as soon as any writer recreates-shm: open the OpenWhispr app once (it self-heals on its next write). The containing dir must also be writable — it is by default (~/Library/Application Support/open-whispr,drwx------, yours). To make the server immune, harden itssqliteJsonopen to retry withimmutable=1when the plain-readonlyopen fails — that fallback only triggers when-shmis absent (i.e. the WAL was already checkpointed), so it sees complete data with no staleness risk. - The watermark is this server's only writable state —
state/watermark.json(overrideOPENWHISPR_STATE). It's howmark_processedkeeps ingestion idempotent; it is not covered by Cos's encrypted backup (which protects the board/guard/config/vault stores), and it's safely reconstructible — at worst the loop re-emits already-routed notes, which dedupe on the board. - Port
8002must be free (lsof -nP -iTCP:8002 -sTCP:LISTEN). It sits between the core bridges (8001board,8003calendar,8004guard,8005vault). A foreign process on it breaks §3 — pick another free port viaOPENWHISPR_BRIDGE_PORTincos.envand re-render. - launchd cannot expand
$VARS. As with every Cos plist, the rendered plist in~/Library/LaunchAgentscarries literal absolute paths and aPATHthat starts with$BREW_PREFIX/bin— launchd never inherits your login shell and can't see an nvm/asdf shim. - The node/simdjson + pm2 gotchas in mcp-bridge-setup apply here too — same Node, same
supergateway, same launchd supervisor. If the bridge dies with a
libsimdjsondyld error after abrew install,brew reinstall node. Don't reintroduce pm2.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

