HabitSpark AI Documentation
Everything you need to know about HabitSpark AI — from your first spark to advanced AI coaching, analytics, and social features.
🚀 Quick Start Guide
Get up and running in under a minute.
Installation
- Download HabitSpark AI from the App Store (iOS) or Google Play Store (Android).
- Open the app and create an account using your email, or sign in with Facebook for seamless social integration.
- Grant notification permissions so we can send you daily reminders.
Onboarding
On your first launch, a 5-step onboarding flow walks you through:
- Selecting your goals (Get Healthier, Be More Productive, Find Inner Peace, Level Up My Life)
- Choosing up to 3 habit categories from 12 options
- Picking your coaching tone (Gentle, Motivational, or Neutral)
- Setting your daily reminder time
Starter habits are created automatically based on your selections — you're ready to spark!
Dashboard Overview
🏠 Home Screen
- Momentum Ring — a 0–100 score showing recent activity, weighted toward the last few days
- Trend Badge — ↑ Rising, → Steady, or ↓ Dipping compared to last week
- "Your Rhythm" chart — bar chart showing completion rates by day of the week
- AI Coach card — personalised insights with contextual badges (AT RISK, NEW PB!, TRENDING UP)
- Habit cards — tap to complete, with weekly dot trackers, streak counts, and smart labels
- Quick Stats — 14-day rate, best streak, and this week's sparks
🧭 Navigation
- Home — daily dashboard with habits and AI insights
- Coach — AI coaching cards, habit suggestions, per-habit tips
- Stats — full analytics with charts, heatmaps, and performance bars
- Badges — achievement system with progress rings
- Leaderboard — friend rankings and social features (when enabled)
✨ Adding & Managing Habits
Build your personalised habit collection.
Adding a New Habit
- Tap the ✨ Explore Sparks icon in the top bar.
- Browse 12 categories — each with a gradient icon and description.
- Tap a category to add it. Free users watch a short ad to unlock; Spark Pro users get instant access.
Editing & Deleting
- Tap a habit card to edit details like name or category
- Long-press a habit card to delete it
- Duplicate habits are automatically prevented — you can't add the same habit twice
Categories
Habits are organised into 12 categories, each with a unique colour and emoji: Healthy Eating 🍎, Fitness 💪, Saving Money 🐷, Mental Wellness 🧘, Productivity ⚡, Sleep Hygiene 🌙, Learning 📚, Relationships 💝, Sustainability 🌿, Career Growth 💼, Housekeeping 🏠, and Journaling ✏️.
🤖 AI Coach & Suggestions
Personalised coaching powered by local analytics + GPT-4o-mini.
How It Works
The AI Coach operates in two layers:
Layer 1: Local Analytics (Free)
An on-device analytics engine analyses your completion dates, streaks, weekly patterns, and day-of-week trends. This powers the AI Coach card on the home screen with instant insights — no API call needed, no subscription required. A built-in database of 1,231 coaching tips across 82 categories provides actionable advice for every habit, served instantly from your device.
Layer 2: GPT Coaching (Spark Pro)
A compact summary of your analytics is sent to GPT-4o-mini for deeply personalised coaching. The AI references your specific habits, streaks, and patterns — like "You're strongest on Tuesdays at 92%!" rather than generic advice.
What You Get
- Hero coaching cards — prioritised by urgency: at-risk habits → declining trends → personal bests → celebrations
- Habit suggestions — AI recommends new habits based on gaps in your routine (e.g., "You track fitness but not nutrition")
- Per-habit tips — tap "Tips →" on any habit for 3 actionable coaching tips
- Adaptive tone — all messages adapt to your chosen tone (Gentle, Motivational, or Neutral)
📊 Progress & Analytics
Visual patterns that help you understand your behaviour.
Stats Dashboard
📈 Charts & Visualisations
- Key Metrics — completion rate, total sparks in 28 days, best-performing habit
- Weekly Trend — smooth line chart showing 9 weeks of completion rates with week-over-week change
- Day Strength Radial — polar chart showing completion rates by day of the week. Best day glows green, weakest glows red
- 28-Day Heatmap — calendar grid where darker purple = more habits completed. Today is outlined
- Habit Performance — each habit sorted by rate with gradient progress bars, PB badges, and sub-stats
- Category Distribution — stacked colour bar showing habit balance across life areas
- AI Insight — a data-driven observation at the bottom (e.g., pattern detection, trend analysis)
Home Dashboard Analytics
- Momentum Score (0–100) — weighted toward recent days. Green (70+), amber (40–70), red (below 40)
- Your Rhythm — 7-bar chart showing last 4 weeks of day-of-week completion rates
- Trend Badge — compares this week vs last week: ↑ Rising, → Steady, ↓ Dipping
🏆 Badges & Achievements
14 badges to earn across three categories.
Streak Badges
Completion Badges
Special Badges
🔔 Notifications & Reminders
Stay on track with customisable nudges.
Daily Reminders
Set during onboarding or anytime in Settings. Choose from preset times (Morning 8:00 AM, Afternoon 1:00 PM, Evening 8:00 PM) or set a custom time.
Encouragement Settings
Fine-tune your motivational messages in Settings → Encouragement:
- Toggle psychological encouragement on/off
- Choose tone: Gentle, Balanced, or Motivational
- Enable/disable specific message types: Milestone Celebrations, Struggle Support, Consistency Praise
🔧 Troubleshooting & FAQ
Common issues and how to fix them.
📱 App not loading
Check your internet connection and restart the app. If the issue persists, clear the app cache in your device settings.
🔕 Notifications not appearing
Ensure notification permissions are granted in your device settings. On Android, check that battery optimisation is turned off for HabitSpark AI.
🤖 AI tips not refreshing
Free users need to watch an ad for fresh tips. Spark Pro users get instant access. If tips are stuck, try clearing the app cache in Settings.
🌐 Language not switching
After changing the language in Settings, restart the app for the change to take effect. HabitSpark supports 7 languages.
📧 Need more help?
Email us at support@habitspark.ai or visit our FAQ page.
🛡️ Privacy & Security
Your data, protected.
- All habit data is stored securely on your device and in Firebase (encrypted)
- We never sell or share your personal data
- The AI Coach receives only a compact statistical summary — never raw personal data
- Analytics are calculated locally on your device first, keeping things fast and private
- Delete your account and all data anytime via Settings → Account
🌍 Languages
HabitSpark AI supports 7 languages.
The entire app interface, AI coaching tips, and notifications are translated. Switch languages anytime in Settings → App Language.
👥 Social & Sharing
Compete with friends and stay motivated together.
Connecting with Friends
Leaderboard