README.md

kibble #

A calorie and nutrition tracker for Galaxy phones: offline first, styled after One UI, with no analytics, no ads and no cloud. AI runs on the phone. The only network use is optional Open Food Facts lookups. The design and the reasons behind it are in docs/architecture.md.

Phase Scope Status
1 Architecture, Room schema, Samsung Health research done
2 App shell, One UI components, diary, manual logging, custom foods, water, quick re-log done
3 On-device AI photo, text and voice logging (Gemini Nano), USDA grounding, review screen done
4 Barcode scanning, Open Food Facts lookup and search with local caching, recipes done
5 Health Connect sync: meals, water and weigh-ins out; weight, steps and active calories in; dedup tests done
6 Adaptive TDEE, goals, insights, widget, export and backup, glass UI done
7 Wear OS app: summary, water and quick add, tile, complication done

Build #

You need JDK 21 and an Android SDK with platform 37.

export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
echo "sdk.dir=/opt/homebrew/share/android-commandlinetools" > local.properties   # or your SDK path
./gradlew test                  # unit tests (nutrition math, parsers, OFF parsing, sync dedup, TDEE estimator, CSV)
./gradlew :app:installDebug     # debug build installs as sh.selkie.kibble.debug, alongside a release build

Modules #

Module What
core:model Pure Kotlin domain types (Nutrients, MealType, …)
core:nutrition Pure Kotlin portion, recipe, energy and budget math, with tests
core:database Room schema (exported to core/database/schemas/) and DAOs
core:data Repositories, DataStore settings, bundled USDA foods (assets/generic_foods.tsv), Open Food Facts client and parser (off/)
core:ai Gemini Nano via ML Kit Prompt API, food matching, meal analysis
core:tdee Pure Kotlin weight trend and adaptive expenditure estimator, with tests against synthetic data
core:wear Pure Kotlin phone ↔ watch protocol over the Wearable Data Layer, with tests
wear Wear OS app (Compose for Wear OS), tile and complication
core:sync Pure Kotlin sync engine over a HealthGateway interface, with dedup tests against a fake Health Connect
core:health Health Connect adapter, Room-backed sync store, sync status
core:designsystem One UI components written in Compose (extended app bar, rounded groups, switch, slider, tabs)
app Screens and navigation

Install on your phone and watch #

Release builds are signed with a local key, so build them on this Mac: ./gradlew :app:assembleRelease :wear:assembleRelease. The key lives in ~/.android/kibble-release.jks and its passwords in ~/.gradle/gradle.properties, neither of which is in the repo. Back that file up. Updates must be signed with the same key, or Android makes you uninstall (and lose your data) first.

Phone (Galaxy Z Fold8):

  1. Settings → About phone → Software information → tap Build number 7 times.
  2. Settings → Developer options → turn on Wireless debugging, open it, and tap Pair device with pairing code.
  3. On the Mac, with both on the same Wi-Fi:
adb pair <ip>:<pairing-port>      # enter the 6-digit code
adb connect <ip>:<port>           # the port shown on the Wireless debugging screen, not the pairing one
adb install app/build/outputs/apk/release/app-release.apk

Watch (Galaxy Watch or any Wear OS 3+ watch):

  1. Settings → About watch → Software → tap Software version 5 times.
  2. Settings → Developer options → turn on ADB debugging and Wireless debugging, then Pair new device.
  3. Pair, connect and install the same way:
adb pair <watch-ip>:<pairing-port>
adb connect <watch-ip>:<port>
adb -s <watch-ip>:<port> install wear/build/outputs/apk/release/wear-release.apk

Open kibble on the phone once so it publishes today's summary. Then add the Calories left tile, or the complication on a watch face.

Setup notes per phase #

  • On-device AI (phase 3): nothing to set up. Gemini Nano runs through the phone's AICore. Supported phones include the Galaxy S25/S26 and Z Fold7/Fold8. AICore downloads the model once, the first time you log a photo. On phones without it, photo logging is unavailable and typed or spoken meals use the offline parser.
  • Barcodes and Open Food Facts (phase 4): nothing to set up. The scanner is Google's code scanner from Play services; the first scan may wait briefly while Play services downloads it. Open Food Facts needs no account or key. Turn it off in Settings → Food data to stay fully offline. OFF data is ODbL-licensed.
  • USDA food data: tools/usda/build_generic_foods.py rebuilds core/data/src/main/assets/generic_foods.tsv from the public-domain FNDDS export. The instructions are in the script.
  • Health Connect and Samsung Health (phase 5): in kibble, Settings → Health Connect → turn on sync and choose what to allow. Each permission is optional. In Samsung Health, open Settings → Health Connect and allow it to read nutrition (and hydration, if offered) and to write weight, steps and activity. Allowing "Access data in the background" lets new weigh-ins arrive while kibble is closed; without it they arrive when you open the app. The Samsung Health Data SDK adapter is not included: it needs an AAR from Samsung's developer site, so active calories come from Health Connect for now.