Menstrual Cycle Tracker for Home Assistant

A privacy-focused Home Assistant integration for tracking menstrual cycles with adaptive prediction algorithms.

Your data stays on YOUR device - No cloud, no external servers, complete privacy.

✨ Key Features

🌍 Multi-Language & Formats - Full English and German UI support with customizable date formats
📊 Adaptive Predictions - Uses rolling averages of your last 3 cycles (not generic 28-day predictions)
🔒 100% Privacy - All data stored locally in Home Assistant
📱 Easy Logging - Simple services to track periods and a variety of symptoms (including temperature sensitivity and custom text)
🎯 Phase Tracking - Menstrual, Follicular, Ovulation, Luteal phases
🏠 Full Automation - Integrate with lights, climate, notifications
⚡ Real-time Updates - Entities update instantly when you log data
🔔 Binary Sensor - Period Active status for automations

📊 How Many Cycles Do You Need?

Cycles	Accuracy	Status
0	N/A	Can start logging
1	±5 days	Basic tracking
2	±3 days	Simple predictions
3	±1-2 days	Recommended ⭐
6+	<1 day	Optimal

Bottom line: Start with what you have! Works with 0 cycles, excellent with 3, optimal with 6+.

🚀 Installation

HACS (Recommended)

Add this repository to HACS:
- Open HACS in Home Assistant
- Click on "Integrations"
- Click the three dots in the top right
- Select "Custom repositories"
- Add this repository URL
- Select "Integration" as the category
- Click "Add"
Install the integration:
- Search for "Menstrual Cycle Tracker"
- Click "Download"
- Restart Home Assistant
Add the integration:
- Go to Settings → Devices & Services
- Click "+ Add Integration"
- Search for "Menstrual Cycle Tracker"
- Follow the setup wizard

Manual Installation

Copy the custom_components/menstrual_cycle_tracker folder to your Home Assistant's custom_components directory
Restart Home Assistant
Go to Settings → Devices & Services → Add Integration → "Menstrual Cycle Tracker"

🔔 Notification Blueprint

A separate blueprint repository is available for notification automations:

Repository: sjfehlen/cycle-tracker-blueprints

Quick import:

Settings → Blueprints → Import Blueprint
URL: https://github.com/sjfehlen/cycle-tracker-blueprints/blob/main/blueprints/automation/menstrual_cycle_notifications.yaml

Or add to HACS → Automation → Custom Repositories → https://github.com/sjfehlen/cycle-tracker-blueprints → Blueprint

⚙️ Setup Wizard

Step 1: Basic Configuration

Tracker Name: Give it a friendly name (e.g., "My Cycle" or "Cycle Tracker")
Date Format: Choose your preferred date format (e.g., %Y-%m-%d, %d.%m.%Y, %m/%d/%y) for backend data and automation service calls.

Step 2: Add Initial Data (Optional)

For best results, enter your last 3 cycles during setup:

Cycle 1 (Most Recent):
  Start: 2026-02-02
  End: 2026-02-06

Cycle 2:
  Start: 2026-01-05
  End: 2026-01-10

Cycle 3:
  Start: 2025-12-09
  End: 2025-12-14

Why 3 cycles?

Medical standard (3 months tracking)
Rolling average algorithm kicks in
±1-2 day accuracy from day one
You can skip this and add data later!

Date format: YYYY-MM-DD

📊 Entities Created

The integration creates a device with these entities:

Binary Sensor

binary_sensor.cycle_tracker_period_active
- State: On/Off (is period happening now?)
- Perfect for automations

Sensors

sensor.cycle_tracker_current_phase
- States: Menstrual, Follicular, Ovulation, Luteal
sensor.cycle_tracker_cycle_day
- Value: Current day in cycle (1, 2, 3...)
sensor.cycle_tracker_next_period
- Value: Predicted next period date
- Attribute: days_until_next_period
sensor.cycle_tracker_period_length
- Value: Average period length in days
sensor.cycle_tracker_cycle_length
- Value: Average cycle length in days
sensor.cycle_tracker_fertile_window
- States: Yes/No
- Attribute: is_pms_window
sensor.cycle_tracker_todays_symptoms
- Value: Number of symptoms logged today
- Attribute: symptoms (list of today's symptom details)

Calendar

calendar.cycle_tracker_cycle_tracker
- Shows past periods, current active period, and all future predicted periods
- Visible on the HA Calendar dashboard

🎮 Services

💡 Smart Tracker Selection: If you only have one tracker installed, you can skip the tracker field in all service calls. Home Assistant will select it automatically! 📅 Easy Date Picking: When using the Home Assistant UI, dates can be comfortably selected using the built-in Calendar Popup instead of manual typing.

Log Period Start

service: menstrual_cycle.log_period_start
data:
  date: "2026-02-02"  # Optional, defaults to today

Log Period End

service: menstrual_cycle.log_period_end
data:
  date: "2026-02-06"  # Optional, defaults to today

Log Symptom

service: menstrual_cycle.log_symptom
data:
  symptom: "cramps"     # Options: cramps, headache, fatigue, bloating, mood_swings, temperature_sensitivity - or any custom text!
  severity: "moderate"  # Severity options: mild, moderate, severe. Temperature options: very_cold, slightly_cold, normal, slightly_warm, very_hot
  date: "2026-02-02"    # Optional, defaults to today

Edit Cycle

service: menstrual_cycle_tracker.edit_cycle
data:
  original_start_date: "01/05/26"  # Identifies which cycle to edit
  new_start_date: "01/06/26"       # Optional, new start date
  new_end_date: "01/10/26"         # Optional, new end date

Delete Cycle

service: menstrual_cycle_tracker.delete_cycle
data:
  start_date: "01/05/26"  # Identifies the cycle to remove

Delete Symptom

service: menstrual_cycle_tracker.delete_symptom
data:
  date: "02/02/26"      # Date the symptom was logged
  symptom: "cramps"     # Exact symptom name to remove

🤖 Quick Automation Examples

One-Tap Logging Buttons

# configuration.yaml
input_button:
  period_started:
    name: Period Started
    icon: mdi:calendar-heart
  period_ended:
    name: Period Ended
    icon: mdi:check-circle

# automations.yaml
automation:
  - alias: "Log Period Start"
    trigger:
      - platform: state
        entity_id: input_button.period_started
    action:
      - service: menstrual_cycle.log_period_start
      - service: notify.mobile_app
        data:
          message: "Period logged! 💪"

  - alias: "Log Period End"
    trigger:
      - platform: state
        entity_id: input_button.period_ended
    action:
      - service: menstrual_cycle.log_period_end

Period Alert (2 Days Before)

automation:
  - alias: "Period Alert"
    trigger:
      - platform: time
        at: "09:00:00"
    condition:
      - condition: template
        value_template: >
          {{ state_attr('sensor.cycle_tracker_current_phase', 'days_until_next_period') == 2 }}
    action:
      - service: notify.mobile_app
        data:
          title: "🩸 Period Alert"
          message: "Your period is predicted to start in 2 days"

Comfort Lighting During Period

automation:
  - alias: "Comfort Lighting"
    trigger:
      - platform: state
        entity_id: binary_sensor.cycle_tracker_period_active
        to: "on"
    condition:
      - condition: sun
        after: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.bedroom
        data:
          brightness_pct: 30
          kelvin: 2700

Fertile Window Alert

automation:
  - alias: "Fertile Window"
    trigger:
      - platform: state
        entity_id: sensor.cycle_tracker_fertile_window
        to: "Yes"
    action:
      - service: notify.mobile_app
        data:
          title: "🥚 Fertility Update"
          message: "You've entered your fertile window!"

📱 Dashboard Card

A companion Lovelace card is available that visualizes your cycle data with color-coded phases, a segmented progress bar, fertile/PMS indicators, symptom chips, and cycle statistics.

Repository: sjfehlen/flow-meter-card

Install via HACS:

HACS → Frontend → Custom Repositories
Add https://github.com/sjfehlen/flow-meter-card as Lovelace category
Install "Menstrual Cycle Tracker Card"
Reload your browser

The card uses a visual editor — just select your Period Active binary sensor and customize which sections to show.

Basic Entities Card

If you prefer a simple entities card:

type: entities
title: 🌸 Cycle Tracker
entities:
  - entity: binary_sensor.cycle_tracker_period_active
    name: Period Active
  - entity: sensor.cycle_tracker_current_phase
    name: Current Phase
  - entity: sensor.cycle_tracker_cycle_day
    name: Cycle Day
  - entity: sensor.cycle_tracker_next_period
    name: Next Period
  - entity: sensor.cycle_tracker_fertile_window
    name: Fertile Window

🧮 How It Works

Adaptive Rolling Average Algorithm

Instead of using a generic 28-day cycle:

Looks at your last 3 cycles
```
Example: 27, 28, 26 days
```
Calculates average
```
(27 + 28 + 26) / 3 = 27 days
```
Predicts next period
```
Last period: Feb 2
Add 27 days = Mar 1
```
Adapts continuously
- Each new cycle updates the average
- Outliers automatically filtered
- Gets more accurate over time

Phase Tracking

Menstrual (Days 1-6): Period active
Follicular (Days 7-13): Between period end and ovulation
Ovulation (Days 13-16): Fertile window
Luteal (Days 16-27): After ovulation until next period

🔒 Privacy & Data

Your data NEVER leaves your device:

✅ Stored locally in Home Assistant
✅ No cloud services
✅ No external servers
✅ No analytics or tracking
✅ You own and control everything

Data location:

/config/.storage/menstrual_cycle.cycles.[entry_id]

Data format:

{
  "cycles": [
    {"start_date": "2026-02-02", "end_date": "2026-02-06"}
  ],
  "symptoms": [
    {"date": "2026-02-02", "symptom": "cramps", "severity": "moderate"}
  ]
}

❓ FAQ

Q: Can I track multiple people?
A: Yes! Add the integration multiple times with different names.

Q: What if I don't remember my last 3 cycles?
A: Skip the initial data step and start logging from today. Predictions will improve after 2-3 cycles.

Q: How accurate are predictions?
A: With 3+ cycles: typically ±1-2 days. Gets better with more data.

Q: Does this work for irregular cycles?
A: Yes, but predictions will be less accurate. The algorithm adapts to your pattern.

Q: Can I edit old data? A: Yes! Use the edit_cycle, delete_cycle, and delete_symptom services. Identify cycles by their start date.

Q: Is this HIPAA compliant?
A: All data stays on your device, so there's no data transmission. However, consult a compliance expert for your specific use case.

🛠️ Troubleshooting

Sensors show "Unknown"

Log at least one period start date
Check date format is YYYY-MM-DD
Check logs: Settings → System → Logs

Integration not loading

Ensure all files are in custom_components/menstrual_cycle_tracker/
Restart Home Assistant completely
Check for errors in logs

Entities not updating after logging

This should update instantly in v2
Try reloading the integration
Check dispatcher is working (no errors in logs)

🗺️ Roadmap

Edit historical cycles via service
Statistics card with charts
Symptom correlation tracking
Calendar entity with predicted periods

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

MIT License - See LICENSE file

🙏 Acknowledgments

Built for the Home Assistant community
Algorithm based on medical cycle tracking standards
Inspired by the need for privacy-focused period tracking

📞 Support

Issues: GitHub Issues
Home Assistant Community: Forum Thread

Made with ❤️ for privacy-conscious cycle tracking

Track your cycle. Own your data. Automate your comfort.

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.claude		.claude
blueprints/automation		blueprints/automation
custom_components/menstrual_cycle_tracker		custom_components/menstrual_cycle_tracker
.gitignore		.gitignore
ACCESS_GUIDE.md		ACCESS_GUIDE.md
CHANGELOG.md		CHANGELOG.md
FILE_LISTING.md		FILE_LISTING.md
GITLAB_SETUP.md		GITLAB_SETUP.md
LICENSE		LICENSE
README.md		README.md
START_HERE.md		START_HERE.md
hacs.json		hacs.json
info.md		info.md

Folders and files

Latest commit

History

Repository files navigation