Skip to content

know that you are breathing

know that you are breathing logo

a fully featured, offline-first meditation app for Android, Wear OS, and Linux — customizable timers, bells, spoken prompts, breathing exercises, recitation counting, mindfulness reminders, history, and backup/sync. the app never requires internet access outside of optional sync.

get the app

release packages (Android, Wear OS, and Linux) are attached to each GitLab release.

on Android, the easiest way to install and stay up to date is Obtainium, which tracks GitLab releases directly. add the app with the repository url https://gitlab.com/johnkneevsource/know-that-you-are-breathing and filter the apks by regular expression:

  • phone/tablet: phone-.*\.apk
  • degoogled devices without Google Play services: fdroid-.*\.apk
  • Wear OS: wear-.*\.apk

on Linux, each release carries .deb, .rpm, .AppImage, .pacman, .zip, .flatpak, and .snap packages; see the packaging guide for details.

documentation

three audiences, three homes:

  • user guide — how to use the app. written for people who meditate, not for people who write code. no technical details beyond what a setting actually does.
  • developer guide — how the codebase works and how to build, test, package, and release it. this is the source of truth for architecture and conventions.
  • architecture decision records — why specific technical choices were made. ADRs are historical; they are not updated when implementation evolves, so read the developer guide for current behavior.

reading order (developers)

new to the codebase? read these in order:

  1. dev-guide/ARCHITECTURE.md — layers, code generation, theming, and the major subsystems.
  2. dev-guide/terminology.md — the canonical glossary mapping user-facing terms to code identifiers. check it before naming anything.
  3. dev-guide/design-system.md — design tokens and shared widgets for building screens.
  4. topic guides as needed:
  5. dev-guide/sync.md — backup bundles, providers, conflict resolution, and Wear OS data-layer sync.
  6. dev-guide/reminders.md — notification scheduling per platform.
  7. dev-guide/audio-assets.md — how bundled sounds are produced and added.
  8. dev-guide/system-dependencies.md — runtime/build libraries per platform.
  9. dev-guide/ci-and-packaging.md — CI pipeline, packaging formats, signing, and release versioning.
  10. dev-guide/wear_qa_checklist.md — manual QA pass for the Wear OS app.
  11. dev-guide/icon-logo-generator.md — tool/generate.dart for launcher icons and brand assets.
  12. dev-guide/PROJECT_PLAN.md — the original phased roadmap. kept for historical context; it is not a statement of current feature status.

released under the MIT license.