wispr-flow-linux

Imported from wispr-flow-linux/wispr-flow-linux (AGENTS.md). Install upstream with npx skills add wispr-flow-linux/wispr-flow-linux. Copyright stays with the author.

AGENTS.md

Required reading

These documents are the source of truth. If anything in this file conflicts with them, they win. Read them before opening a non-trivial issue or PR.

• docs/reference/ipc-contract.md — the IPC contract the clean-room helper implements: command surface, wire framing, message shapes, keycodes (with companion keycodes.json / commands.json). The technical source of truth for helper behaviour.
• CONTRIBUTING.md — what we accept, what goes upstream to Wispr, the bash + Rust style requirements, the AI-attribution policy.
• docs/index.md — entry point for the operator/contributor docs (building, configuration, troubleshooting, decisions, learnings).
• docs/styleguides/bash_styleguide.md — shell conventions (forked from YSAP). Tabs, 80 cols, [[ ]], no set -e.
• SECURITY.md — vulnerability reporting; what's in scope vs. what belongs to Wispr.

This file is a fast reference for the highest-leverage rules and the project's accumulated conventions. New policy goes in the style guides or CONTRIBUTING.md.

Project overview

This is an unofficial Linux port of the proprietary Wispr Flow voice-dictation app (an Electron 42 / electron-forge app shipped as a Squirrel Windows installer). It is two things:

1. A repackaging pipeline (scripts/, build.sh) that extracts the app, patches its bundle for Linux, rebuilds native modules, stages a Linux Electron, and produces .deb / .rpm / AppImage packages.
2. A clean-room Rust helper that reimplements the one native capability Wispr Flow ships only for macOS (Swift) and Windows (C#): injecting transcribed text into the focused application. It is built from the documented IPC contract (docs/reference/) and contains no Wispr Flow code. It now lives in its own repo (wispr-flow-linux/helper); see the Repo layout below.

Repo layout

The project spans two repositories under the wispr-flow-linux org:

• wispr-flow-linux/wispr-flow-linux (this repo) — the public-domain build scripts and the local packaging makers.
• wispr-flow-linux/helper — the clean-room Rust helper. It was extracted from this repo and no longer lives here as a local source tree. The helper is consumed as a prebuilt binary pinned in helper-version.txt and staged via the HELPER_BIN env var (build-linux.sh resolves it).

The hosted distribution layer — the gh-pages APT/DNF tree, the v* tag Releases, the publish/heartbeat workflows, and a wispr-flow-linux/worker Cloudflare Worker fronting pkg.wispr-flow-linux.dev — is maintainer-run and fails closed with no human gate (D-011). See RELEASING.md and the "Pull request policy" in CONTRIBUTING.md before touching it.

This repo's tree:

• build.sh — top-level orchestrator: dispatches the staging pipeline and the per-format packaging makers (--build deb|rpm|appimage, --clean, --doctor).
• scripts/
  • setup/ — host detection, dependency install, Wispr Flow / Electron download helpers. installer-pin.sh is the pinned upstream installer (version, URL, sha256): builds download exactly that and verify it; only check-wispr-version.yml resolves upstream's latest.json (resolve-installer-url.sh) and rewrites the pin (write-installer-pin.sh).
  • patches/ — the app patches: helper-resolver.sh (adds the 'linux' helper-path branch), mac-gates.sh (gates the macOS Applications-folder guard to darwin), and the V8 14.8 better-sqlite3-multiple-ciphers compat patch. verify-patches.sh static-greps the repacked bundle for the markers.
  • packaging/ — deb.sh, rpm.sh, appimage.sh makers; shared signature <maker>.sh <dist_dir> <version> <arch>.
  • launcher-common.sh — the runtime /usr/bin/wispr-flow launcher library.
  • doctor.sh — the wispr-flow --doctor diagnostic surface.
  • build-linux.sh — the Phase-0 staging pipeline (see safety rules below).
• helper-version.txt — the pinned helper release tag fetched from the helper repo and staged via HELPER_BIN.
• docs/reference/ — the documented stdin/fd-3 IPC protocol (ipc-contract.md
  • keycodes.json / commands.json).
• tests/ — bats unit tests, per-format artifact tests, and the manual VM-matrix validators.
• docs/ — building / configuration / troubleshooting / decisions / learnings / style guides.
• nix/, flake.nix — Nix packaging.
• .github/workflows/ — CI gates (shellcheck, codespell, test-flags, tests) that run on every push/PR, plus the tag-driven release/publish pipeline (ci.yml build→test→release→APT→DNF→AUR, reusable build-amd64/build-arm64/test-artifacts, check-wispr-version, apt-repo-heartbeat, cleanup-runs, update-flake-lock). The publish chain runs on a v* tag push; see RELEASING.md. The worker lives in its own repo (wispr-flow-linux/worker).

Code style

Bash

All shell scripts follow the Bash Style Guide:

• Tabs for indentation, lines under 80 chars (exception: URLs and regex).
• [[ ]] for conditionals, $(...) for substitution.
• Single quotes for literals, double quotes for expansions.
• Lowercase variables; UPPERCASE only for constants/exports.
• local in functions. No set -e (it interacts badly with $(...) capture and function returns — check status explicitly: cmd || handle_err). No eval. No POSIX [ ... ]. No backticks.

Lint with shellcheck (and actionlint for workflows) before pushing. Fix the underlying issue; a per-line # shellcheck disable=SCXXXX with a why-comment is the last resort.

Rust

The helper's code and its cargo fmt / cargo clippy --all-targets -- -D warnings / cargo test gates live in its own repo (wispr-flow-linux/helper). This repo consumes the prebuilt binary pinned in helper-version.txt.

Docs / CHANGELOG

• One declarative sentence then a code block or list at the top of every doc page — no "In this guide we will…" preamble.
• Lowercase kebab-case filenames in docs/. Order lives in docs/index.md.
• Troubleshooting headings are the literal symptom, not editorialized prose.
• CHANGELOG.md follows Keep a Changelog 1.1.0: bullets under Added/Fixed/Changed/etc.

Learnings

The docs/learnings/ directory holds hard-won technical knowledge from building the port — things not obvious from the code alone. Consult the relevant entry before working on a subsystem; add a new entry when you discover something non-obvious that would save the next contributor (human or AI) significant time.

• kwin-zbus-tokio.md — the async-zbus-on- tokio dispatch deadlock that left KDE active-app empty, and the fix.
• gnome-shell-extension.md — install, relogin requirement, MRU focus fallback, the Introspect pivot.
• electron42-v8-sqlite.md — the V8 14.8 ABI patch that lets better-sqlite3-multiple-ciphers compile.
• ispackaged-rename.md — why an electron-named launcher silently breaks DB migrations ("no such table").
• wayland-injection.md — in-process /dev/uinput virtual keyboard + ext-data-control clipboard.
• global-key-monitor.md — push-to-talk and the shortcut recorder are fed by helper KeypressEvents (XInput2 on X11, evdev /dev/input on Wayland); the app has no hotkey detection of its own.
• helper-spawn-env.md — the app spawns the helper with a replacement env (no process.env), starving it of WAYLAND_DISPLAY/DISPLAY so injection silently falls to the no-op stub while recording/shortcuts keep working; helper-env.sh restores the env.
• platform-gates.md — the darwin/win32 carve-outs Linux falls through: the .linux-matches-no-CSS-rule bug behind the shifted side menu, the three gate-shape rules (isMac?: is usually fine, isWindows?: lands Linux on mac defaults, if(win32){} no-else drops functionality), and beautifying the minified bundle with prettier --ignore-path /dev/null to re-audit a new Wispr version.
• patching-minified-js.md — the rules for writing patches that survive re-minification: [\w$]+ (not \w) for identifiers, anchor on developer strings over churning names, assert the match count, inject a marker for idempotency, and verify against shipped bytes (not a beautified copy). Read before touching scripts/patches/.
• test-methodology.md — how a green shell test earns its colour: run subshells away counter mutations, anchors need a near-miss fixture, one FAIL branch must hit the real tool, [PASS] only on parsed data, and the mutation check (revert the fix, watch a test go red). Read before adding or reviewing a bats test.

Cross-VM testing memory

Operational knowledge from manual VM validation (e.g. issue #32) lives in .claude/memory/ — committed so it carries across test VMs and survives agent session resets (only .claude/worktrees/ is gitignored). Read it before doing VM validation work, and append new hard-won learnings there (launch quirks, keybind/window/mic gotchas, per-issue validation status). It complements docs/learnings/ (code-level) with environment/runtime test knowledge.

GitHub / CI workflow

• Use the gh CLI for GitHub interactions.
• Branch off issue numbers: fix/123-description or feature/123-description.
• Reference issues in commits/PRs with #123 or Fixes #123.
• CI gates (.github/workflows/ci.yml): shellcheck, codespell, flag-parsing, and bats, run on every push/PR. On a v* tag, the same workflow runs the build→test→release→APT/DNF/AUR publish chain. See RELEASING.md.
• Claude Code hooks (.claude/settings.json): .claude/hooks/pre-pr-lint.sh runs the CI shellcheck line, codespell over tracked files, actionlint on changed workflows and (when a shell or bats file changed) bats tests/*.bats before any git push, and blocks the push on a failure; .claude/hooks/session-start.sh installs the missing tools at session start with a passwordless sudo, or says which are missing.

Issues, PRs, and commits

Keep them short and plain. An issue says what is wrong and what should be true instead, in a few sentences. A PR says what changed and why this way, enough for a reviewer to decide where to look. The evidence (test counts, command output, the reasoning that ruled out the obvious approach) goes in the commit body, where someone deep-diving is already reading, and the diff is the authority over both. No headers, no checklists, no bullet retelling of the diff, no em-dashes. Say what was deliberately left out.

Reference the issue with Fixes #123 (or Refs #123). A commit subject states what changed; the body states why, with the evidence. Credit reused or cherry-picked contributor work by handle, in the body.

AI-assisted work discloses with one trailer line at the end of a PR or issue body, using the actual model name:

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Commits carry Co-Authored-By: Claude <claude@anthropic.com>. Comments carry no trailer.