Contributing

Voktty is maintained with a strong product direction and limited review bandwidth. Alignment and a focused change matter as much as implementation quality.

Before coding

  1. Read VOKTTY.md.
  2. Read the relevant architecture guide under docs/.
  3. Check ROADMAP.md for scope and direction.
  4. For a non-trivial feature, discuss the design in Discord or an issue before opening a pull request.

Keep changes focused

One pull request should represent one logical change. Do not mix unrelated formatting, refactors or cleanup into a feature or documentation fix. Preserve user work already present in the working tree.

Quality bar

Voktty targets a lightweight, production-grade desktop app. Contributions should preserve:

  • correctness and failure handling;
  • performance in terminal, PTY, AI and filesystem hot paths;
  • security at IPC, filesystem, network and AI boundaries;
  • macOS, Linux, Windows and WSL parity;
  • lazy loading and bounded resource use;
  • tests for core invariants.

Branches and commits

Use a focused branch with one of these prefixes:

Prefix Use
feat/ New feature
fix/ Bug fix
chore/ Tooling or maintenance
docs/ Documentation
perf/ Performance work
security/ Security hardening

Commit messages should be short, imperative and free of em dashes. Do not include secrets or generated artifacts.

Pull request checklist

  • [ ] The change matches the architecture and roadmap.
  • [ ] The affected module and source of truth were read.
  • [ ] Tests cover the changed contract or invariant.
  • [ ] pnpm lint passes.
  • [ ] pnpm check-types passes.
  • [ ] pnpm test passes.
  • [ ] Rust checks pass when Rust or IPC code changed.
  • [ ] mkdocs build --strict passes when public docs changed.