harken
CLAUDE.md12 starsChanged 3 months agoApache-2.0View on GitHub
Local, offline audio transcription CLI (whisper.cpp via direct FFI + vendored sources) with WhatsApp chat-export support and an MCP server mode (harken mcp). Rust crate harken — full port from Python is done, the Python tree is gone. Architecture map: docs/ARCHITECTURE.md. Local context: if an untracked hub/ dir exists, read hub/README.md (personal notes, roadmap, ADRs — never commit it). - make check — full local CI: fmt + clippy -D warnings + test + cargo audit + cargo machete. Run…
- Installs packages
In this repositoryOne other file it gives its agents.
- transcribe-audioSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
stdout stays clean: All progress, logs, and summaries go to stderr.
- Very specific: line 138
Bump
y(0.7 → 0.8): when anything a consumer depends on breaks: a pub item removed or renamed, a field added to a pub struct whose fields …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md 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
CLAUDE.md — harken
Local, offline audio transcription CLI (whisper.cpp via direct FFI + vendored sources) with WhatsApp
chat-export support and an MCP server mode (harken mcp). Rust crate harken — full port from
Python is done, the Python tree is gone. Architecture map: docs/ARCHITECTURE.md.
Local context: if an untracked hub/ dir exists, read hub/README.md (personal
notes, roadmap, ADRs — never commit it).
Commands
make check— full local CI:fmt+clippy -D warnings+test+cargo audit+cargo machete. Run before claiming anything done.cargo test— 166 integration tests, instant and offline.cargo test --test ffi_smoke_test -- --ignored— opt-in smoke test that loads a real whisper context throughsrc/ffi.rs(skips ifggml-tiny.binis not already cached; never runs in CI). Run it after touchingsrc/ffi.rs,build.rs, or the submodule pin — the 166 tests above useFakeEngineand cannot catch an FFI mistake.cargo build— needs a C++ toolchain (whisper.cpp is compiled in) and thevendor/whisper.cppsubmodule checked out (git submodule update --init --recursive);build.rspanics with that hint if it is missing.dist plan/dist build— cargo-dist release artifacts.make install-dev-tools— installs cargo-audit + cargo-machete.
Inviolable rules
- The 166 tests in
tests/are the behavior SPEC (the original 88 were ported from the Python suite's 81; the MCP server added 27, 2026-07-28 compliance added 22 more intests/mcp_protocol_test.rs, the 2026-08-25 issue sweep added 21 acrosstests/audio_test.rs,tests/model_test.rsandtests/mcp_status_test.rs, and the warm-up follow-ups added 4 intests/mcp_status_test.rsplus 4 schema-drift guards intests/mcp_schema_test.rs). A behavior change requires consciously changing the corresponding test — never "fix" a test to make code pass. - stdout stays clean. All progress, logs, and summaries go to stderr. The
one exception is
harken mcp, where stdout is the protocol channel: it carries only newline-delimited JSON-RPC frames, and logs still go to stderr. - Exit codes:
0ok (skips are not failures),1at least one transcription failed,2input error (bad path, bad date, no chat log). - Tests stay offline. The batch pipeline is generic over the
Transcribertrait; tests useFakeEngine(tests/common/mod.rs). Never write a test that downloads a model, loads a real whisper context, or touches the network.
Commits
Conventional Commits, small and atomic: <type>(<scope>): <subject>. Types are
the canonical set only (feat fix perf refactor test docs build
ci chore); scopes are the module touched (mcp, engine, ffi, audio,
model, batch, whatsapp, writers, cli, ggml, registry, skill,
release, bench). Imperative, lowercase after the colon, no trailing period,
≤72 chars. Enforced by .github/workflows/commits.yml — its own workflow
because ci.yml has a paths-ignore that would skip a docs-only PR. The length
rule alone is waived for *[bot] authors: Dependabot's generated subject spends
60 chars before the crate name, so all but the shortest names overshoot 72 and
no human can fix it. Type and scope still apply, and for cargo they come from
commit-message.prefix in .github/dependabot.yml.
History before v0.5.0 uses imperative prose subjects and larger commits; don't
match it. Do match its bodies — prose wrapped at ~76 columns explaining why
and naming the tradeoff, the test-count delta, and what was actually verified.
Docs for a change ride in that change's commit (see the mirroring rule under
Skill / plugin); a standalone docs(...) commit is only for documentation with
no code behind it.
Toolchain
- Edition 2024, MSRV 1.88 (
rust-versioninCargo.toml). The floor is 1.88 twice over: let-chains, and the dependency graph (icu_*viaurl). ThemsrvCI job runscargo +1.88 check --all-targets --locked— the+1.88is load-bearing, since a barecargo checkwould honourrust-toolchain.tomland stop testing the floor while still reporting green. rust-toolchain.tomlpins the compiler to 1.97.1, and.github/workflows/ci.ymlpinsdtolnay/rust-toolchain@1.97.1to match. Bump the two together. Pinned rather than floating becauseclippy -D warningsis a gate: a new stable shipping a new lint reddens a green tree. The file is inCargo.toml'sexclude— cargo packages it by default, which would drag this toolchain onto everycargo install harken.- cargo-audit and cargo-machete are version-pinned in the Makefile's
install-dev-toolsand in thedepsCI job. Bump both together, or a localmake checkand CI can disagree about findings. CI gets them as prebuilt binaries throughtaiki-e/install-action— the tool versions there are explicit, so the action's version database never decides what gets installed. - Every action in
ci.ymlis pinned by commit SHA, with a# v6-style comment that Dependabot reads to resolve the version. Keep the comment in sync when bumping.dtolnay/rust-toolchainis addressed as@v1with an explicittoolchain:input, not as@1.97.1: those version refs are branches whose commits are unreachable from the default branch, so pinning one by SHA is the "impostor commit" pattern and Dependabot cannot track it. - Dependabot (
.github/dependabot.yml) covers actions weekly and cargo monthly, grouped into a single PR each because a PR costs a full 5-target matrix run. Cargo majors are excluded from the group so one breaking bump cannot redden the safe ones. dist planis also a drift check onrelease.yml. It fails (exit 255, printing the diff) whenever that file no longer matches whatdist generatewould produce — so hand edits and stray Dependabot bumps are caught on every PR and tag, not discovered later. The actions dist hardcodes (actions/checkout,swatinem/rust-cache,actions/{download,upload}-artifact) are therefore ignored independabot.yml: bumping them there yields a PR that can never merge. They move only whencargo-dist-versionmoves.
Build gotchas
vendor/whisper.cppis a git submodule pinned to a tag (v1.7.6). A plaingit clonedoes not populate it;build.rscompiles those sources directly withcc, so whisper.cpp never goes through CMake.src/ffi.rsmirrorsvendor/whisper.cpp/include/whisper.hby hand — bumping the submodule means re-checking that header field by field.- Never remove the arch flags or
NDEBUGfrombuild.rs. ggml selects its CPU kernels at compile time; without-mavx2 -mfma -mf16cthe binary runs scalar code (measurable asvcvtph2psdropping to zero inobjdump) and withoutNDEBUGggml's operator asserts stay in. Seedocs/ARCHITECTURE.md. .cargo/config.tomlsetsCMAKE_POLICY_VERSION_MINIMUM=3.5— this is now only about opus: the tree vendored byaudiopus_sysdeclares a cmake minimum that CMake 4 (GitHub macOS runners) rejects. Do not remove.- libopus: locally it links dynamically via pkg-config (
opus-develon Fedora); on CI runners with no libopus-dev, the vendored copy is embedded statically. Different on purpose — a release Linux binary must NOT listlibopus.soinldd. .github/workflows/release.ymlis GENERATED bydist generate. Never edit it by hand; changedist-workspace.tomland regenerate.pr-run-mode = "upload": a pull request builds the full 5-target matrix without publishing. Use a PR to rehearse anything that touches the release path — the toolchain pin,build.rs, the submodule — instead of finding out from a redv*tag, which is how v0.4.0 died.
Distribution
cargo-dist 0.32. Pushing a v* tag builds GitHub Releases for 5 targets
(linux x64/arm64, macOS x64/arm64, windows x64; arm64-linux on a native
ubuntu-24.04-arm runner) plus shell/powershell installers. The crate is
published on crates.io (cargo publish is manual, run it on the same commit
as the v* tag). Cargo.toml version and .claude-plugin/plugin.json
version must bump together.
Which number to bump. Cargo's 0.y.z rules, applied to the whole
product — the crate's public API, the CLI surface, and the MCP surface:
- Bump
y(0.7 → 0.8) when anything a consumer depends on breaks: apubitem removed or renamed, a field added to apubstruct whose fields are allpub(it breaks literal construction — this is what made v0.8.0 a minor), a required trait method added, a CLI flag removed or its default changed, a tool removed from the MCP catalog or an argument made required. - Bump
z(0.7.0 → 0.7.1) for anything purely additive or internal: a new flag, a new tool, a new optional field in a result, bug fixes, dependency bumps, performance work.
The cadence has been fast (0.5.0 through 0.8.0 in four days) and that is fine — each bump was forced by this rule, not chosen. If a release feels like a jump, the question to ask is "what broke?", and the answer should be nameable in one line. When it is not, it is a patch.
A release that only changes what an agent reads — tool descriptions, result
text, tools/list payload shape — still ships, because the published binary is
what clients talk to: docs on main describing behaviour the released binary
does not have is the situation v0.7.0 was cut to end.
Skill / plugin
.claude/skills/transcribe-audio/SKILL.md and .claude-plugin/ (plugin.json,
marketplace.json) ship in this repo and are part of the product. Any CLI change
(flags, defaults, output layout, install one-liner) must be reflected there in
the same change.
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.

