[!CAUTION]
Not a medical device. Do not use it for treatment decisions. faBolus is experimental software
under active development. It is not FDA-cleared or approved and has not been clinically
validated. Do not rely on it to make or carry out any insulin-dosing, treatment, or other clinical
decision. It is for software development and evaluation only: always confirm every reading and dose
directly on your pump and CGM, and talk to your healthcare provider about your therapy.
faBolus
A remote-bolus and status-viewing app for the iPhone, designed to be pump-agnostic. The
iPhone owns the pump's Bluetooth connection; a Garmin Venu 3S watch and the Home/Lock Screen
widgets (including Quick Bolus) are thin remotes that relay confirmed commands to the phone;
they never talk to the pump directly.
Today it works with one pump: the Tandem t:slim X2, via TandemKit. (Tandem's
Mobi isn't supported in this build: the app declines to pair with one.) The app talks to the
pump only through a backend interface, so support for other pumps can be added without forking,
see ARCHITECTURE.md.
Dexcom Share (optional): glucose normally arrives through the pump. faBolus can also poll
Dexcom Share as a fallback so a reading keeps flowing if the pump's own glucose goes stale. The
pump stays the primary source, and a Share reading is shown marked, never as current. See
Glucose (Dexcom Share).
Built by Zev and Tia in tandem.
[!WARNING]
Experimental, in development. faBolus is an independent, open-source project in development
for experimental use. It is not FDA-cleared; if you build or use it, you assume all
responsibility. Not affiliated with, endorsed by, or a product of Tandem Diabetes Care or
Dexcom.
📖 Documentation
Full docs (a no-experience-required build guide, usage, and customization) live at the
documentation site:
💬 Feedback
Bug, confusion, or an idea, technical or not? See Send feedback, or go
straight to the feedback form
(or email [email protected]). faBolus is experimental and not
FDA-cleared. For anything urgent about your therapy, contact your healthcare provider.
Using it alongside the official Tandem app
The pump pairs to one controller at a time, so faBolus and the official t:connect app can
both be installed but only one is connected at once, and switching is a full re-pair with a new
6-digit code, not a quick toggle (the pump doesn't store two pairings, and the code can't be shared
between apps). faBolus isn't a full replacement either: some pump settings can only be changed in
t:connect. Pick faBolus as your everyday controller (it reconnects with no code) and pair t:connect
only when you need an official-app-only setting, then re-pair faBolus. More in the
FAQ and Pairing.
Layout
Packages/faBolusCore/ # in-repo SwiftPM package: the stable contracts + neutral models
# (PumpBackend, PumpCapabilities, PumpAlert, RemoteCommand, GlucoseSource + GlucoseArbiter)
Packages/ShareClient/ # Dexcom Share follower, vendored from LoopKit/dexcom-share-client-swift (MIT)
ios/faBolus/ # iOS host app, owns the pump connection; tabbed UI
ios/faBolus/Data/ # backends (TandemBackend, MockBackend) + BackendRegistry + hosts
ios/faBolus/Data/Sources/ # the Dexcom Share glucose follower + its keychain credential store
ios/faBolusWidgets/ # Lock/Home Screen widgets (incl. Quick Bolus)
Shared/ # WidgetShared (App Group snapshot) + widget bolus intents
schema/ # THE phone↔remote message contract, single source of truth
hosts/ # sketches for hosting the remotes from another app (e.g. Loop)
docs/ # the documentation site (MkDocs Material)
This is narrow main: a small, hardware-validated core. A number of surfaces an earlier build of
this app had (other remotes, other CGM sources, an advisory meal-detection assistant, and more) live
on experimental and their own dev/<surface> branch instead; see BRANCHES.md §1.2c for the full
roster and why.
New pumps and new host apps are added in-tree behind stable interfaces, not by forking: see
ARCHITECTURE.md for the two seams and CONTRIBUTING.md
for step-by-step "add a pump backend" / "host the remotes" guides.
- The iOS app + widgets are targets of one Xcode project (
faBolus.xcodeproj), generated from
project.yml with XcodeGen. Depends on TandemKit via
SPM.
- The Garmin (Connect IQ / Monkey C) remote lives in its own repo,
faBolusGarmin; the iPhone-side bridge stays
here and talks to it over the shared
schema/.
- The widgets read a snapshot the app publishes to a shared App Group; they can't drive
Bluetooth, so they show the last published value with its age (older than 6 minutes shows marked).
Build (quick reference)
Full walkthrough: docs/build. In short:
git clone --recurse-submodules https://github.com/faBolus-app/TandemKit.git
git clone https://github.com/faBolus-app/faBolus.git
cd faBolus
./scripts/generate-project.sh # generates faBolus.xcodeproj (auto-detects the Garmin SDK)
open faBolus.xcodeproj # set your Team under Signing & Capabilities, then Run
Requires Xcode 16+ and an Apple ID (free works; paid recommended).
Garmin is optional at build time. scripts/generate-project.sh auto-detects the Connect IQ
Mobile SDK for iOS: if it's not present, the app builds without Garmin (no SDK needed) and shows
a note where Garmin pairing would be. To use a Garmin watch, place the Connect IQ SDK where
project.yml expects it (see docs/build) and re-run the script (force Garmin
on/off with FABOLUS_GARMIN=1/0). Plain xcodegen generate still works.
Status
The protocol/BLE/auth core (TandemKit) supports read-only monitoring, JPAKE
pairing, and a signed bolus path validated on hardware. This app layer is under active
development on top of it.
Acknowledgments
faBolus is built on pumpX2 by James Woglom
(@jwoglom). His reverse-engineering of the Tandem pump's Bluetooth
protocol is the foundation of this entire project. TandemKit is a Swift port of
that work, validated byte-for-byte against pumpX2's cliparser oracle. faBolus would not exist
without it. (faBolus is an independent reimplementation, not a fork of, affiliated with, or
endorsed by pumpX2/controlX2.)
It also draws on the wider LoopKit / Loop
ecosystem: the app's visual design and parts of this documentation take inspiration from Loop and
LoopDocs.
Full attributions are in NOTICE.md.
License & trademark
Code is MIT-licensed (see LICENSE). faBolus™ is a trademark of Zev Granowitz; the license
covers the source code, not the name, logo, or branding. Forks are welcome under the MIT terms;
please don't use the faBolus name in a way that implies your fork is the official project. See
NOTICE.md for details.
