HabitHub Calendar Export

The HabitHub calendar app (package ID com.rstudioz.habits) was an Android app that allowed you to track habits. The app required payment for CSV export and was discontinued on the Play Store between 2022-2025. This tool processes scrolling screenshots of your calendar and extracts habit tracking data (green/red/blue/gray circles) into a structured CSV format using a hybrid approach: OpenCV for image splitting + Multimodal LLM for data extraction.

Installation

# Clone the repository
git clone git@github.com:creme332/habithub-export.git
cd habithub-export

# Create virtual environment and install dependencies
uv sync

Note: You also need to install Tesseract OCR on your system:

• Ubuntu/Debian: sudo apt-get install tesseract-ocr
• macOS: brew install tesseract
• Windows: Download from GitHub

Setup

1. Create a .env file in the root of the project with your OpenAI API key:

   cp .env.example .env
   # Edit the .env file and add your API key
   nano .env
   # Replace 'your-api-key-here' with your actual key

   Get your API key from: https://platform.openai.com/api-keys

Usage

Run Complete Pipeline

# Activate virtual environment
source .venv/bin/activate

# Run with default image (input/sample-screenshot.jpg)
python main.py

# Or specify a custom image path
python main.py path/to/your/screenshot.jpg

This will:

1. Phase 1: Split your screenshot into individual month images
2. Phase 2: Extract habit data from each month using OpenAI's GPT-5-mini Vision API
3. Phase 3: Consolidate, validate, and export data to CSV
4. Output final CSV to output/habit_data.csv

Run Individual Phases

# Phase 1 only: Split screenshot into months
python split_screenshot.py

# Phase 2 only: Extract data from split months
python extract_with_llm.py

# Phase 3 only: Consolidate extracted data to CSV
python consolidate_data.py

Output

The tool generates:

• output/habit_data.csv - Final CSV output with all habit data
• output/summary_report.json - Statistics and summary information
• output/split_months/ - Individual month images
• output/split_metadata.json - Metadata about detected months
• output/extracted_data.json - Raw extracted habit tracking data
• debug/month_boundaries_detected.png - Visualization of detected month boundaries