Contributing

Contributing

TypeWhisper for Linux is a community Linux port, and setup-specific bug reports, fixes, and tests are all welcome. This page covers how to report issues, build from source, run the tests, open a pull request, and report security problems.

Reporting a setup-specific issue

Linux desktop behavior varies widely by distribution, desktop environment, and especially Wayland implementation. When you open an issue, include:

• Your Linux distribution
• Your desktop environment
• Your display server (X11 or Wayland)
• Clear reproduction steps
• Any relevant logs

For URL-detection problems specifically, the Error Log section on the About page records a one-line AT-SPI walk diagnostic per unique state. Entries look like:

AT-SPI URL walk: process=firefox matched-app='Firefox' nodes-walked=N best-score=... result=...

matched-app=none means the browser is not exposing AT-SPI, and result=null with a non-null best-score means the walker reached the address bar but did not recognise it. Including this line helps pinpoint which step failed. See Troubleshooting for more on diagnosing these cases.

Building from source

You need the .NET 10 SDK to build from source (prebuilt releases bundle the runtime, so the SDK is only needed for source builds).

git clone https://github.com/csmashe/typewhisper-linux.git
cd typewhisper-linux
dotnet build
dotnet run --project src/TypeWhisper.Linux

For installing a clickable desktop launcher and the full set of install formats, see Installation.

Running the tests

The project ships automated tests under tests/. Run them with dotnet test:

# Core logic tests
dotnet test tests/TypeWhisper.Core.Tests/TypeWhisper.Core.Tests.csproj

# Linux app tests
dotnet test tests/TypeWhisper.Linux.Tests/TypeWhisper.Linux.Tests.csproj

You can scope to a focused set of tests with --filter, for example:

dotnet test tests/TypeWhisper.Core.Tests/TypeWhisper.Core.Tests.csproj \
  --filter "FullyQualifiedName~CleanupServiceTests"

Beyond the automated suite, manual verification matters because the behavior that breaks on Linux is usually desktop-specific. Useful manual checks include dictating into a browser text field, into a terminal with a terminal-safe profile, into an Electron app, and on both Wayland and X11 if you have them — plus confirming the clipboard fallback after a forced paste failure. When you change an HTTP API endpoint or a plugin, test it directly (for example with curl against the local API, with the API server enabled in General settings).

Pull request process

Open a pull request against the linux branch. The PR template asks you to:

• Summary — describe what the PR changes
• Related Issue — link the issue it addresses, if any (e.g. Closes #123)
• Test Plan — confirm the relevant items:
  • dotnet test
  • Built and ran locally on Linux
  • Tested the changed functionality manually
  • Checked desktop-environment or X11/Wayland behavior when relevant
  • No regressions in existing features
• Notes — anything reviewers should know before looking at the change

Reporting security issues

Do not open a public issue for security vulnerabilities. Use GitHub's private vulnerability reporting for the repository. You can expect acknowledgement within 48 hours and a fix targeted within 7 days for critical issues.

Include the affected version/commit/package, your distribution, desktop environment, display server, and CPU architecture, clear reproduction steps, the security impact and affected data or privileges, and any relevant logs or proof-of-concept details that avoid exposing secrets or personal data. Good-faith research is welcome; there is no paid bug bounty program. See License & Trademark for licensing terms.

Relationship to upstream

This repository is a Linux desktop port forked from the upstream TypeWhisper project, which provides the macOS and Windows versions. If the TypeWhisper project releases an official Linux version, or if this port is merged into the main TypeWhisper branch, the maintainer plans to switch to the upstream Linux version instead. Until then, this branch is maintained as a practical Linux port.

Related pages

• Plugin SDK — interfaces and contracts for building plugins
• Installation — building, installing, and the prebuilt release formats
• Troubleshooting — diagnosing desktop-specific issues

---

Changelog

Date	Change
2026-06-17	Initial version.