harken

Local audio transcription for Claude Code and any agent — batch, fully offline, no API key.

A single static binary powered by whisper.cpp. No Python, no ffmpeg, no runtime dependencies — audio decoding (opus, mp3, m4a, wav, flac, …) happens in-process.

Why

Voice notes, meeting recordings, and WhatsApp PTT audio often contain sensitive content. harken transcribes everything on your own machine: no audio, and no transcript, ever leaves the device. There is no API key, no upload step, no cloud dependency.

• Runs on CPU by default — no GPU required.
• The model loads once per run and is reused for every file in a batch.
• Two modes: transcribe loose audio files (or whole folders), or point it straight at a WhatsApp chat-export .zip and let it pull out only the voice notes.

Install

One-liner (Linux/macOS):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/montezuma-p/harken/releases/latest/download/harken-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/montezuma-p/harken/releases/latest/download/harken-installer.ps1 | iex"

Other options:

cargo binstall harken        # prebuilt binary via cargo-binstall
cargo install harken --locked  # build from source (needs cmake + a C++ toolchain)

Building from source with CMake >= 4 and no system libopus? The vendored opus tree declares an old CMake minimum; prepend CMAKE_POLICY_VERSION_MINIMUM=3.5 to the cargo install line.

Prebuilt binaries and default source builds target AVX2/FMA/F16C (Intel Haswell, AMD Excavator, or newer). Building for the machine you are on, and want its full instruction set? Prepend HARKEN_NATIVE=1 to the cargo install line.

If you are building from a git checkout, initialize the vendored whisper.cpp submodule first:

git clone --recurse-submodules https://github.com/montezuma-p/harken
# or, if you already cloned it:
git submodule update --init --recursive

Use with Claude Code

harken ships an Agent Skill that teaches Claude Code when and how to transcribe audio locally instead of reaching for a cloud API. Install it as a plugin:

/plugin marketplace add montezuma-p/harken
/plugin install harken@harken

The skill invokes the harken binary and knows how to install it with the one-liner above if it is missing. (Alternatively: clone the repo and the project-scoped skill in .claude/skills/ is picked up automatically, or copy/symlink .claude/skills/transcribe-audio/ into ~/.claude/skills/.)

Usage

Batch mode — files, folders, or globs

# One file
harken voice-note.opus

# A whole folder, recursively, written to ./transcripts by default
harken ~/Downloads/meeting-recordings/

# Glob, custom output dir, JSON output, force re-transcription
harken "recordings/*.m4a" --out ./out --format json --force

# Larger model, auto-detect language instead of the pt default
harken recording.wav --model medium --lang auto

Flags: --out DIR (default ./transcripts), --model (default small), --lang (default pt; --lang auto to auto-detect), --format (txt/json/srt, default txt), --device (default cpu), --force (re-transcribe even if the output file already exists).

Every file gets <out>/<stem>.<format>; a running manifest.jsonl records one line per transcription. Progress and a final summary print to stderr; exit code is 1 if any file failed, 0 otherwise (skips don't count as failures).

Privacy note: output files — transcripts and manifest.jsonl — contain the full transcribed text. Default output dirs (transcripts/, *-transcripts/) are gitignored in this repo; keep yours out of version control too.

WhatsApp export mode — transcribe voice notes straight from a chat export

Export a chat from WhatsApp ("Export chat" → with media) and point harken at the resulting .zip:

# All voice notes in the export
harken whatsapp "WhatsApp Chat with Maria.zip"

# Only a date range, with the model biased to Portuguese
harken whatsapp export.zip --from 2026-07-01 --to 2026-07-15 --lang pt

# Also write a merged chat transcript with each transcript inlined
harken whatsapp export.zip --from 2026-07-01 --to 2026-07-15 --merge --out ./maria-july

Flags: --out DIR (default ./<zip-stem>-transcripts), --from / --to (YYYY-MM-DD, inclusive on both ends), --merge, plus --model, --lang, --format, --device, --force as in batch mode.

harken whatsapp locates the chat log inside the zip, selects only the messages carrying an audio attachment within the date range, extracts those files to <out>/audio/, and transcribes them (same skip/force, manifest, and progress behavior as batch mode — it reuses the same batch pipeline). With --merge, it also writes <out>/_chat.transcribed.txt: the full original chat, with each transcribed attachment line immediately followed by a >> [transcript] <text> line. Everything outside the date range, and every non-audio attachment, is left untouched.

Both iOS and Android export formats are auto-detected (per chat, from the first message header). Android date order (day-first vs month-first) is inferred from the chat itself; when every date is ambiguous (all components <= 12), day-first is assumed.

Models & hardware

--model accepts a whisper.cpp ggml model name or a path to a local .bin file:

• small (default, ~466 MB) — good accuracy/speed tradeoff on CPU; fine for most voice notes and casual recordings.
• medium (~1.5 GB) — noticeably better accuracy (accents, background noise, technical vocabulary), at a real CPU time cost.
• Quantized variants — append -q5_0, -q5_1, or -q8_0 to any name (e.g. small-q5_1, ~182 MB): ~60% smaller download, marginal quality loss.
• Also: tiny, base, large-v1, large-v2, large-v3, large-v3-turbo, and the .en English-only variants.

With the default model, an hour of audio transcribes in ~22 minutes on a 2017 desktop CPU — no GPU involved. Measured on an Intel i5-7400 (4 threads), 10 minutes of synthetic Portuguese speech, single run, GNU time -v, model download excluded (reproduce with make bench):

Table measured on v0.3.1. The v0.4.0 engine (in-repo FFI instead of whisper-rs) came out within 3% of it in a controlled A/B on the same machine — five interleaved pairs, small — so these numbers still describe the current build. Single-run figures drift more than that between sessions, which is why the comparison was done interleaved rather than by re-running the table.

The chosen model is downloaded once, on first use, to ~/.cache/harken/models. Subsequent runs reuse the cached model with no network access.

CPU is the safe default everywhere. Passing --device with anything other than cpu enables GPU offload when the binary was built with a GPU backend (Metal/CUDA/Vulkan — via the vendored whisper.cpp build).

Development

make check   # fmt + clippy + tests + cargo-audit + cargo-machete

Tests never load a real Whisper model — the transcription engine is a trait, and the suite runs against a fake, so it is instant and offline.

License

MIT

Bundles whisper.cpp (MIT) as the pinned submodule at vendor/whisper.cpp, compiled into the binary — see its license.