johnmiddleton12/my-whoop

Analysis updated 2026-05-18

★ 117PythonAudience · developerComplexity · 4/5Setup · hard

Mindmap

mindmap
  root((my-whoop))
    What it does
      Reads WHOOP data
      Bluetooth reverse engineering
      Local storage
    Tech stack
      Swift iOS app
      Python protocol package
      FastAPI server
      TimescaleDB
    Use cases
      Personal data ownership
      Self hosted server
      Protocol study
    Audience
      Developers
      WHOOP owners
    Notes
      WHOOP 4.0 only
      Not medically validated

mindmap root((my-whoop)) What it does Reads WHOOP data Bluetooth reverse engineering Local storage Tech stack Swift iOS app Python protocol package FastAPI server TimescaleDB Use cases Personal data ownership Self hosted server Protocol study Audience Developers WHOOP owners Notes WHOOP 4.0 only Not medically validated

What do people build with it?

USE CASE 1

Read your own WHOOP 4.0 band's data locally without sending it to WHOOP's cloud.

USE CASE 2

Self-host a server that stores your heart rate and strain data in a time-series database you control.

USE CASE 3

Study the shared protocol file to understand how WHOOP's Bluetooth data format works.

What is it built with?

SwiftPythonFastAPITimescaleDBDocker

How does it compare?

	johnmiddleton12/my-whoop	joeseesun/qiaomu-ai-prd	virtualluoucas/chronicles-ocr
Stars	117	118	116
Language	Python	Python	Python
Setup difficulty	hard	easy	hard
Complexity	4/5	—	4/5
Audience	developer	vibe coder	researcher

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1h+

Requires reverse-engineered Bluetooth pairing plus an optional Docker server with your own config and API key.

In plain English

This project is an unofficial, open-source iOS app for reading biometric data directly from a WHOOP 4.0 fitness band over Bluetooth. Rather than relying on WHOOP's own cloud infrastructure, it stores your data locally on your phone and, optionally, on a self-hosted server you control. The author reverse-engineered the Bluetooth protocol by observing the data traffic between the band and a device they own personally. The repository is split into several components. The iOS app, written in Swift, handles connecting to the band via Bluetooth, decoding the incoming data, and storing it on-device using a local database. A shared protocol description file acts as a single reference for how to decode the raw data, and both the phone app and the optional server use the same file so they stay in sync. There is also a Python package called whoop-protocol for the server side, and a Mac tool used during development to inspect Bluetooth traffic. The optional server component runs with Docker and uses FastAPI alongside TimescaleDB, a database suited for time-series data like heart rate readings over time. Setting it up involves copying an example environment file, filling in your configuration, and running a single Docker command. The iOS app needs a configuration file with your server address and API key before it will compile. The project is explicit about its legal standing. It contains only original code and documented observations from the author's own device. No WHOOP software, firmware, or artwork is included. The disclaimer notes that this is personal and educational use, that the outputs are not medically validated, and that the work exists specifically for interoperability with hardware the user already owns. Currently only the WHOOP 4.0 is supported. Earlier or later generations use different Bluetooth protocols and are not handled by this codebase. The README credits several prior community reverse-engineering projects whose findings informed the protocol decoder, particularly for HRV and strain calculations.

Copy-paste prompts

Prompt 1

Explain how this repo's iOS app connects to a WHOOP 4.0 band over Bluetooth without using WHOOP's cloud.

Prompt 2

Walk me through setting up the optional Docker server with FastAPI and TimescaleDB from this repo.

Prompt 3

Using this repo's protocol file, explain how it decodes raw Bluetooth data into heart rate and strain values.

Prompt 4

What configuration do I need to set in the iOS app before it will compile according to this repo?

Frequently asked questions

What is my-whoop?

An unofficial iOS app that reads your WHOOP 4.0 band's biometric data directly over Bluetooth, storing it locally instead of in WHOOP's cloud.

What language is my-whoop written in?

Mainly Python. The stack also includes Swift, Python, FastAPI.

How hard is my-whoop to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is my-whoop for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.