Project Info
Inspiration
The inspiration for Ghost Runner came from a staggering reality of modern life: the sedentary epidemic. In 2026, the average adult spends over 9 hours a day sitting—a habit that has become as harmful to cardiovascular health as smoking. We realized that for students and office workers, the "lonely jog" or a walk around the block feels like a chore because it lacks the immediate feedback and dopamine hits of the digital world. We wanted to create an "escape hatch" from the chair. By blending the addictive mechanics of gaming with the physical necessity of movement, we sought to turn the mundane act of standing up and running into a high-stakes, cinematic quest where you aren't just a user—you’re the hero.
What it does
Ghost Runner is an immersive, eyes-free AR fitness experience designed to break the cycle of sitting. It uses spatial audio and real-time GPS to turn your environment into a competitive arena. The "Creep" Mechanic: The app projects a "Digital Ghost" (your past PR or a friend's record) into your 360-degree soundstage. As the Ghost closes the gap, you’ll hear rhythmic footsteps and heavy breathing getting louder and closer in 3D space. Psychological Pacing: If the Ghost gets within 2 meters, a pulsing heartbeat triggers in your ears, activating your natural "fight-or-flight" response to push you through the fatigue. Hands-Free HUD: While it features a beautiful neon radar for selecting "Ghosts" and viewing 3D Mapbox routes, the experience is designed to be fully auditory, allowing you to focus on the terrain, not your phone. Victory Soundscapes: Crossing the finish line ahead of your Ghost rewards you with an immersive, spatial crowd cheer, providing the instant gratification that traditional fitness tracking lacks.
How we built it
React Native (Expo) for the mobile app Firebase Authentication for login/signup Cloud Firestore for data storage (users, runs, friends) Expo Location + Maps for GPS tracking Expo AV + Haptics for audio feedback React Navigation for app navigation
Challenges we ran into
GPS Jitter: Standard GPS data is noisy, often making the Ghost "teleport" or jump around. We had to implement a Kalman Filter to smooth the path data for a realistic audio experience. Audio Latency: Delivering real-time 3D sound that responds to micro-changes in position was a hurdle. We had to optimize our React Native bridge to ensure the footsteps didn't "lag" behind the GPS updates. Battery Efficiency: Running high-frequency GPS, 3D mapping, and spatial audio simultaneously is a massive drain. we optimized the background processing to ensure the app could survive long-distance runs.
Accomplishments we're proud of
We are incredibly proud of creating a "Heads-Up" AR experience that doesn't require glasses or a screen. Successfully mapping a digital coordinate to a physical sound that "creeps up" behind a user was a massive technical win. We've managed to turn the most boring part of a healthy lifestyle into something that feels like a scene from a thriller movie.
What we learned
We learned that sound is a more powerful motivator than sight for high-intensity activity. Designing for "Audio UX" taught us how to use volume and panning to communicate complex data (like distance and speed) without words. We also gained deep experience in geospatial math and the intricacies of mobile sensor fusion.
What's next
Social "Territory War": A map-based mode where students can "claim" areas of campus by outrunning the local "Ghost" of that zone. Haptic Feedback: Integrating watch haptics to "nudge" the user when the Ghost is about to pass them. Smart "Sedentary" Alerts: Connecting to desktop activity to trigger a "Ghost Chase" the moment the app detects you’ve been sitting for over 60 minutes.
Ghost Runner
Race your past self with a live ghost overlay and spatial audio cues.
What is included
- GPS route recording with live distance and pace stats.
- Ghost racing engine that compares your current distance to a past run.
- Spatial audio manager wired for breathing, footsteps, heartbeat, and victory.
- Screens: Home, Run, Ghost Select, Ghost Run, Summary.
Setup (SDK 54)
- Install dependencies:
npm install
- Align Expo packages:
npx expo install --fix
- Install the Babel preset used by
babel.config.js:
npm install --save-dev babel-preset-expo
- Configure Firebase env vars (see below).
- Add audio files and wire them in
src/config/audioSources.js. - Start the app:
npm run start
Firebase config
This project reads config from Expo public env vars:
EXPO_PUBLIC_FIREBASE_API_KEYEXPO_PUBLIC_FIREBASE_AUTH_DOMAINEXPO_PUBLIC_FIREBASE_PROJECT_IDEXPO_PUBLIC_FIREBASE_STORAGE_BUCKETEXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_IDEXPO_PUBLIC_FIREBASE_APP_ID
You can set these in a local .env file or your shell environment.
Audio assets
Place your audio files under assets/audio/ and update:
src/config/audioSources.js
Example:
export const audioSources = {
breathing: require('../../assets/audio/heavy-breathing-14431.mp3'),
footsteps: require('../../assets/audio/heavy-walking-footsteps-352771.mp3'),
heartbeat: require('../../assets/audio/thudding-heartbeat-372487.mp3'),
cheer: require('../../assets/audio/crowd-cheering-383111.mp3'),
};
Project structure
App.js
src/
config/
screens/
services/
utils/
Notes
react-native-mapsmay require platform-specific config for iOS and Android.- The ghost engine currently compares route distance by elapsed time.
- Firebase Auth is not initialized yet; runs save with
userId: "anon"until auth is wired. - Runs are stored locally in AsyncStorage and synced to Firestore when available.
Expo Go + SDK compatibility
- Expo Go on iOS only supports the latest SDK. This project targets SDK 54.
- If the QR does not scan, open Expo Go and use “Enter URL” with the
exp://link.
Troubleshooting
EMFILE: too many open files: install Watchman (brew install watchman) or runulimit -n 8192then restart Metro.- Watchman recrawl warning:
watchman watch-del '<project>' ; watchman watch-project '<project>'.
Analysis
View
Metric
- 21
- 9
- 2
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- FirebaseIn code
- JavaScriptIn code
- ReactIn code
3 of 3 appear in the indexed code.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
261 KB
Source files
42
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
raymonsadhra/Ghost-Runner
50 files · 1.4 MB · @ 0a1f2e6
Structure
Interface
12 files · 24%Screens, components and styles rendered to the user.
Application logic
22 files · 44%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- JavaScript97%
- Markdown3%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 22- @react-native-async-storage/async-storage
- @react-navigation/bottom-tabs
- @react-navigation/native
- @react-navigation/stack
- expo
- expo-av
- expo-blur
- expo-haptics
- expo-linear-gradient
- expo-location
- firebase
- react
- react-native
- react-native-chart-kit
- react-native-gesture-handler
- react-native-maps
- react-native-safe-area-context
- react-native-screens
- +4 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.