TuxFlow 0.2.0 (Alpha)

TuxFlow 0.2.0 (Alpha) is a reliability, privacy, and trust release. It ships automatic updates, fixes every high-severity issue from a full code audit, and makes releases verifiable.

Automatic updates

• TuxFlow now checks GitHub for new versions (at most once a day, and you can turn it off in Settings). The AppImage updates itself in one click after verifying the download against the release's SHA256SUMS — no checksum, no install. Source installs get a notice with a link instead.
• New tuxflow update command for the terminal.
• The AppImage embeds zsync update information, so AppImageUpdate works too.
• The check sends a single anonymous HTTPS request to the GitHub API. Nothing about you or your dictations leaves the machine.

Reliability

• Fixed a race where releasing the shortcut a fraction of a second after pressing it could leave the microphone recording until the safety timeout.
• Failures are no longer silent: if the transcript can't be copied or pasted (missing clipboard tool, no ydotool), the app now says so instead of pretending it worked — in a banner in the control center, the tray, and a notification.
• The control center now recovers automatically when the background service has crashed, instead of failing forever until it was restarted by hand.
• Slow disks can no longer stall the background service while it saves your history, and CLI errors print a readable message instead of a Python traceback.

Privacy

• Transcription history, recordings, and TuxFlow's directories are now private to your user account (0600/0700) instead of world-readable, matching how the config file was already protected. Existing installs are healed automatically on first run.

Dictation quality

• Dictionary entries with deliberate casing ("iPhone", "macOS") are no longer mangled at the start of a sentence.
• Spoken punctuation commands ("new paragraph", "comma", …) now work as the first words of an utterance.

Verifiable releases

• Every release now ships a SHA256SUMS file:

  sha256sum -c SHA256SUMS

• The AppImage build tools are pinned to exact versions and verified by checksum instead of tracking upstream "continuous" builds.

Under the hood

• Test suite grew from 58 to 213 tests; coverage from 59% to 71%, now reported in CI. The core transcription path is exercised in CI for the first time.
• CI is green on Linux and macOS. As before, macOS support is untested on real hardware — reports welcome.

This is an alpha. Expect rough edges, and please file issues.

Install

chmod +x TuxFlow-0.2.0a1-x86_64.AppImage
./TuxFlow-0.2.0a1-x86_64.AppImage

Needs glibc 2.39+ (Ubuntu 24.04+, Fedora 40+, Debian 13+). See the README for the host tools it uses and for installing from source.

TuxFlow 0.1.0a1 — first alpha

TuxFlow is a free, local-first voice dictation app for Linux and macOS. Hold a
global shortcut, speak, release it, and a local Whisper model transcribes and
pastes into whatever app you were already in. No account, no subscription, no
API key, and no audio leaves the machine.

This is the first alpha. It works end to end, but it has had one user on one
machine — expect rough edges, and please file issues.

Install

Linux — download the AppImage

chmod +x TuxFlow-0.1.0a1-x86_64.AppImage
./TuxFlow-0.1.0a1-x86_64.AppImage doctor
./TuxFlow-0.1.0a1-x86_64.AppImage          # opens the control center

It carries its own Python, GTK 4, libadwaita, and faster-whisper. It needs glibc
2.39 or newer, so Ubuntu 24.04+, Fedora 40+, or Debian 13+.

A recorder (pw-record, arecord, or ffmpeg), a clipboard tool
(wl-clipboard or xclip), and ydotool/wtype for automatic paste stay on
the host deliberately — they talk to PipeWire, the compositor, and /dev/uinput,
and the host's own copies do that far better than a bundled one could. Most
desktop installs already have all three, and doctor names anything missing.

The AppImage does not start at login by itself; run ./TuxFlow-*.AppImage daemon
from your session's autostart, or use the installer below for a managed service.

No macOS binary yet — building one that macOS will actually open needs an Apple
Developer signature. macOS installs from source for now.

Either platform — install from source

git clone https://github.com/Robertg761/TuxFlow.git
cd TuxFlow
./scripts/install.sh

The installer never touches system Python. It installs desktop packages with
dnf/apt/pacman/zypper or Homebrew, builds an isolated environment under
~/.local/share/tuxflow/venv, links ~/.local/bin/tuxflow, adds a launcher
entry, starts a login service, and finishes with tuxflow doctor.

Remove it again with ./scripts/uninstall.sh (--purge also deletes settings,
models, and history).

What works

• Hold-to-dictate global shortcut — the XDG Desktop Portal on Linux, a Quartz
  event tap (hold 🌐 fn) on macOS
• Recording via PipeWire, ALSA, or FFmpeg on Linux; AVFoundation or SoX on macOS
• Local transcription with tiny through large-v3 and turbo
• Clipboard and automatic paste on Wayland, X11, and macOS
• GTK 4 / Libadwaita control center, local history, dictionary replacements,
  voice snippets, filler-word cleanup, spoken punctuation
• A CLI: tuxflow toggle, status, transcribe, doctor

Known limitations

• macOS is essentially unverified. Every macOS backend was written and
  tested on Fedora. CI runs the test suite, imports, and tuxflow doctor on
  macOS runners, but nothing has exercised the event tap, the keycodes, the
  permission prompts, or real recording on a Mac. Treat macOS as experimental
  and please report what breaks.
• Linux is verified on Fedora 44 / Wayland / PipeWire only. Other distributions
  and X11 should work but have not been run.
• Automatic paste on Wayland needs /dev/uinput access for ydotool. Without it
  TuxFlow copies to the clipboard and tells you to press Ctrl+V. Rerun the
  installer with --with-uinput to set it up.
• The first dictation downloads the model (~500 MB for the default small).
• The AppImage is x86_64 only, and it has been run on Fedora 44 / KDE / Wayland
  and on an Ubuntu 24.04 CI runner — nowhere else yet.
• No Flatpak, no Homebrew tap, no distro packages, and no macOS binary yet.

Requirements

Python 3.11+, a desktop session, and a microphone. Linux: GTK 4, Libadwaita,
PyGObject, a recorder, and wl-clipboard — the installer handles these on Fedora,
Ubuntu/Debian, Arch, and openSUSE. macOS: 12 or newer with Homebrew.

Start troubleshooting with tuxflow doctor; it names your platform and checks
each integration point separately.