GPTCoach is an LLM-based health coaching chatbot designed to develop a physical activity plan that is tailored to the needs, abilities, and goals of a client. GPTCoach implements the onboarding conversation from Active Choices, an evidence-based health coaching program, uses counseling strategies from motivational interviewing, and can query and visualize a user's health data from a wearable device through tool use.
This reposity contains code that accompanies the publication:
Matthew Jörke, Shardul Sapkota, Lyndsea Warkenthien, Niklas Vainio, Paul Schmiedmayer, Emma Brunskill, James A. Landay. 2025. GPTCoach: Towards LLM-Based Physical Activity Coaching, In CHI Conference on Human Factors in Computing Systems (CHI '25).
Our system architecture consists of four main components:
- A Google Cloud Firestore database containing health data and conversation histories. We also use Firebase Authentication to manage user accounts.
- An iOS application that fetches three months of historical data using Apple's HealthKit API and uploads the data to our database. This application is built using the Stanford Spezi Template Application.
- A Python/FastAPI backend server that handles all LLM logic and tool call execution.
- A Typescript/React a frontend web interface that displays the chat interface and interactive data visualizations.
backend/
contains the code for our Python/FastAPI backend server.frontend/
contains the code for our Typescript/React frontend web interface.ios/
contains the code for our iOS application.prompts/
contains the prompt templates used by our backend server. Please see our copyright notice below regarding the use of the Active Choices materials.
- Create a new Google Cloud Firestore project.
- In your Firebase project settings:
- Add a new web app and copy the Firebase config into
frontend/utils/firebase.ts
. - Add a new iOS application with the appropriate bundle ID and copy the
GoogleService-Info.plist
file intoios/HealthKitUpload/Supporting Files
. - Add a new Firebase Admin SDK service account and download the private key JSON file. Copy this file into
backend/serviceAccount.json
. Copy your Firebase project name intobackend/firebase.py
.
- Add a new web app and copy the Firebase config into
- If you would like to use the Firebase emulator, you can follow these instructions to configure the emulator.
- You will need to run
firebase init
from the root directory, select the Firestore and Emulators options, and configure your project. - Then, you can run the emulator with
firebase emulators:start
. - The backend and frontend are configured to connect to the emulator by default, unless the
PROD
environment variable is set toTrue
. You can manually override this behavior infirebase.py
andfirebase.ts
. - The iOS application is configured to connect to the emulator whenever the app is running on a simulator. You can override this behavior by setting the
useFirebaseEmulator
inFeatureFlags.swift
- You will need to run
- Create a new OpenAI account and generate an API key. Copy this key into
backend/gpt/openai_client.py
. - Install the required Python packages with
pip install -r requirements.txt
. We recommend using a virtual environment or conda. - Start the backend server from the
backend
directory withuvicorn main:app --port 5000 --reload
.
- Install the required Node packages with
npm install
from thefrontend
directory. - Start the frontend server with
npm run dev
.
- Open the
ios/HealthKitUpload.xcodeproj
file in Xcode. - Select your development team in the Signing & Capabilities tab and make sure that the bundle ID matches the one you used to register your iOS app in the Firebase console.
- Choose your target (simulator or physical device) and build the application.
Note: You will need a Mac to build and run the iOS application. You will need to install Xcode from the App Store. By default, the simulator does not have any HealthKit data available, though you can add sample data using the Health app. To test with real data, you will need to run the application on a physical iPhone.
Our project uses the REUSE Standard for copyright and licensing. Please note that not all files may be licensed under the same terms:
-
Open-Source Code (MIT License)
All code inbackend
,frontend
, andios
is licensed under the MIT license. -
Active Choices Prompts (Proprietary)
The dialogue state prompts inprompts/dialogue
are not open source and are © 2025 Board of Trustees of the Leland Stanford Junior University. Any use or adaptation requires prior written approval from the Stanford HEARTS Lab Faculty Director. SeeLICENSES/ActiveChoices.txt
for details.
For questions, please contact Matthew Jörke at joerke@stanford.edu. Please note that GPTCoach is a research prototype and will not be actively maintained. We can provide limited technical support and cannot guarantee that the software will run in the future.
Matthew Jörke, Shardul Sapkota, Niklas Vainio, Paul Schmiedmayer were the primary developers of the project.
Niall Kehoe and Anthony Xie made significant contributions to the frontend and backend codebase during a summer 2023 CURIS internship. Romuald Thomas significantly contributed to the backend in a Fall 2023 research internship.
Evelyn Hur,
Bryant Jimenez,
Dhruv Naik,
Evelyn Song, and
Caroline Tran contributed to the iOS application as part of the course CS342: Building for Digital Health in Winter 2024.
Bryant Jimenez made subsantial contributions to the BulkUpload
functionality in SpeziHealthKit
.
We thank the CS342 course staff for supervising the student team, including
Paul Schmiedmayer,
Andreas Bauer,
Philipp Zagar, and
Nikolai Madlener.