# Hevy ↔ Sense 2 Companion

**Interactive Hevy workout tracking on Fitbit Sense 2.**

This repo is now built around the correct gym architecture: **the phone controls itself**. No Tailscale, no remote ADB, no server-to-phone dependency while training.

## Production gym architecture

```text
Fitbit Sense 2 app
  ↕ peerSocket
Fitbit companion inside the Fitbit Android app
  ↕ fetch('http://127.0.0.1:18090')
HevyBridge APK on the Pixel
  ↕ AccessibilityService
Hevy Android app
```

The watch shows:

- current exercise
- set X/Y
- target weight × reps
- rest timer countdown
- buttons: **DONE**, **SKIP**, **-15**, **+15**

Actions from the watch are sent to the local Pixel bridge and reflected in Hevy via Accessibility clicks.

## Components

| Path | Purpose |
| --- | --- |
| `path-a-companion/` | Fitbit Sense 2 watch app + phone companion |
| `phone-bridge/` | Android APK running on the Pixel; exposes localhost API and controls Hevy |
| `backend/` | Cloud debug/download backend only. Not required in gym. |
| `path-b-hevy-live/` | Hevy reverse-engineering research |
| `path-c-android-bridge/` | Android bridge research notes |

## Build Fitbit .fba

```bash
cd path-a-companion
npm install
FITBIT_QA_COMMANDS=1 npx fitbit-build
```

Output:

```text
path-a-companion/build/app.fba
```

Upload the `.fba` to GAM as a private app.

## Build HevyBridge APK

```bash
cd phone-bridge
ANDROID_HOME=/opt/android-sdk gradle assembleDebug --no-daemon
```

Output:

```text
phone-bridge/app/build/outputs/apk/debug/app-debug.apk
```

Install:

```bash
adb install -r phone-bridge/app/build/outputs/apk/debug/app-debug.apk
```

Then enable **Hevy Bridge** in Android Accessibility settings.

## Local API

Base URL from Fitbit companion:

```text
http://127.0.0.1:18090
```

Endpoints:

- `GET /health`
- `GET /api/hevy/live`
- `POST /api/hevy/action`
- `GET /api/hevy/window`

## Cloud backend role

`backend/server.py` is now only for:

- serving latest `.fba` from GitHub Releases
- serving handoff docs
- remote debugging fallback

It is **not** the gym path.

## Docs

- [`HANDOFF-REPORT.md`](HANDOFF-REPORT.md) — Complete project handoff
- [`phone-bridge/README.md`](phone-bridge/README.md) — Android bridge details
- [`OPTIONS-RACE-SUMMARY.md`](OPTIONS-RACE-SUMMARY.md) — Architecture options