agentleFS
montezuma-pmontezuma-p/harken/CLAUDE.md

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

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
  1. Very specific:

    stdout stays clean: All progress, logs, and summaries go to stderr.

    line 35
  2. Very specific:

    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 …

    line 138

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 through src/ffi.rs (skips if ggml-tiny.bin is not already cached; never runs in CI). Run it after touching src/ffi.rs, build.rs, or the submodule pin — the 166 tests above use FakeEngine and cannot catch an FFI mistake.
  • cargo build — needs a C++ toolchain (whisper.cpp is compiled in) and the vendor/whisper.cpp submodule checked out (git submodule update --init --recursive); build.rs panics 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 in tests/mcp_protocol_test.rs, the 2026-08-25 issue sweep added 21 across tests/audio_test.rs, tests/model_test.rs and tests/mcp_status_test.rs, and the warm-up follow-ups added 4 in tests/mcp_status_test.rs plus 4 schema-drift guards in tests/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: 0 ok (skips are not failures), 1 at least one transcription failed, 2 input error (bad path, bad date, no chat log).
  • Tests stay offline. The batch pipeline is generic over the Transcriber trait; tests use FakeEngine (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-version in Cargo.toml). The floor is 1.88 twice over: let-chains, and the dependency graph (icu_* via url). The msrv CI job runs cargo +1.88 check --all-targets --locked — the +1.88 is load-bearing, since a bare cargo check would honour rust-toolchain.toml and stop testing the floor while still reporting green.
  • rust-toolchain.toml pins the compiler to 1.97.1, and .github/workflows/ci.yml pins dtolnay/rust-toolchain@1.97.1 to match. Bump the two together. Pinned rather than floating because clippy -D warnings is a gate: a new stable shipping a new lint reddens a green tree. The file is in Cargo.toml's exclude — cargo packages it by default, which would drag this toolchain onto every cargo install harken.
  • cargo-audit and cargo-machete are version-pinned in the Makefile's install-dev-tools and in the deps CI job. Bump both together, or a local make check and CI can disagree about findings. CI gets them as prebuilt binaries through taiki-e/install-action — the tool versions there are explicit, so the action's version database never decides what gets installed.
  • Every action in ci.yml is 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-toolchain is addressed as @v1 with an explicit toolchain: 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 plan is also a drift check on release.yml. It fails (exit 255, printing the diff) whenever that file no longer matches what dist generate would 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 in dependabot.yml: bumping them there yields a PR that can never merge. They move only when cargo-dist-version moves.

Build gotchas

  • vendor/whisper.cpp is a git submodule pinned to a tag (v1.7.6). A plain git clone does not populate it; build.rs compiles those sources directly with cc, so whisper.cpp never goes through CMake. src/ffi.rs mirrors vendor/whisper.cpp/include/whisper.h by hand — bumping the submodule means re-checking that header field by field.
  • Never remove the arch flags or NDEBUG from build.rs. ggml selects its CPU kernels at compile time; without -mavx2 -mfma -mf16c the binary runs scalar code (measurable as vcvtph2ps dropping to zero in objdump) and without NDEBUG ggml's operator asserts stay in. See docs/ARCHITECTURE.md.
  • .cargo/config.toml sets CMAKE_POLICY_VERSION_MINIMUM=3.5 — this is now only about opus: the tree vendored by audiopus_sys declares a cmake minimum that CMake 4 (GitHub macOS runners) rejects. Do not remove.
  • libopus: locally it links dynamically via pkg-config (opus-devel on Fedora); on CI runners with no libopus-dev, the vendored copy is embedded statically. Different on purpose — a release Linux binary must NOT list libopus.so in ldd.
  • .github/workflows/release.yml is GENERATED by dist generate. Never edit it by hand; change dist-workspace.toml and 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 red v* 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: a pub item removed or renamed, a field added to a pub struct whose fields are all pub (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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.