HerCycle — Women's Cycle Intelligence
Built on the insight that women's biology is cyclical, not linear. Every month has four distinct hormonal seasons — each unlocking different cognitive, emotional, and physical capabilities. HerCycle reads your biometrics and tells you which season you're in, then takes action accordingly.
The Four Seasons
| Season |
Phase |
Days |
What's Amplified |
| 🌑 Winter |
Menstrual |
1–5 |
Introspection, pattern recognition, deep insight, rest & recovery |
| 🌱 Spring |
Follicular |
6–14 |
Creativity, optimism, new ideas, social energy, starting things |
| ☀️ Summer |
Ovulation |
~14 |
Communication, charisma, negotiation, peak performance, visibility |
| 🍂 Autumn |
Luteal |
15–28 |
Detail orientation, completion, editing, boundaries, deep focus |
Data Sources
HerCycle reads from:
- Whoop API — HRV, recovery score, sleep quality, skin temperature (ovulation signal)
- Cycle tracking — stored in WhoopClaw DB (
cycle_tracking table), or inferred from skin temp patterns
- Phase inference — if no explicit cycle log, estimate phase from skin temp trend + HRV patterns
See references/whoop-api.md for data access patterns.
Action Modules
Actions are pluggable. Each module takes the current phase + biometrics and returns a recommendation or triggers an action.
Current modules:
- 🎵 Music — Spotify mood matching via a phase-aware playlist engine (see your WhoopClaw
spotify_engine.py or bring your own)
- 💪 Training — Push hard (follicular/ovulation) vs restore (menstrual/luteal)
- 🥗 Nutrition — Iron-rich (menstrual), protein/carb cycling (luteal), light & fresh (ovulation)
- 📅 Calendar — Phase-aware scheduling nudges (big meetings → ovulation, deep work → luteal)
- 💬 Social — Energy level signal ("high charisma window" vs "protect your bandwidth")
To add a new action module: see references/action-modules.md.
Usage
Check current phase:
"What phase am I in?" / "What's my cycle season today?"
Phase-aware recommendation:
"Should I push hard at the gym today?"
"What should I eat this week?"
"Is this a good week for a big presentation?"
Trigger an action:
"Play music for my phase" / "Give me a playlist for my cycle phase"
Setup Requirements
HerCycle requires a running WhoopClaw instance — an open-source FastAPI backend that handles Whoop OAuth, cycle tracking, and biometric storage. Search GitHub for "WhoopClaw" to find an implementation, or build your own against the Whoop Developer API.
Prerequisites:
- Whoop API credentials — register at developer-dashboard.whoop.com to get your
WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET
- WhoopClaw running locally — clone, configure
.env, and start the server (uvicorn main:app)
- Whoop account connected — complete the OAuth flow via WhoopClaw's
/whoop/authorize endpoint
Once running, configure WHOOPLAW_BASE_URL to point to your instance (default: http://localhost:8000).
Key endpoints HerCycle uses:
GET /whoop/recovery — latest recovery + HRVGET /cycle/current-phase?telegram_id=<id> — current cycle phaseGET /cycle/predictions?telegram_id=<id> — next period predictionGET /whoop/metrics/skin-temp — skin temperature trend (ovulation signal)
Always pull live data before making recommendations. Do not rely on stale cached values.
Philosophy
"Every month I experience four seasons... in this season, certain sensitivity and capacity is amplified." — Chloé Zhao, Oscar-winning director (BBC 100 Women)
The goal is not to manage around the cycle. It's to move with it — scheduling, eating, training, socialising, and creating in alignment with what's naturally amplified. The cycle is the intelligence. HerCycle makes it legible.
1---2name: hercycle3description: Women's cycle intelligence companion. Reads Whoop biometric data (HRV, recovery, sleep, skin temperature) and menstrual cycle phase to understand which hormonal "season" the user is in — and takes smart, phase-aware actions. Use when the user asks about their cycle phase, energy, mood, what to eat, how hard to train, when to schedule important meetings, or wants any Whoop-powered recommendation tailored to their hormonal cycle. NOT a period tracker — a biometric intelligence layer that treats the cycle as a source of power, not a problem.4---56# HerCycle — Women's Cycle Intelligence78Built on the insight that women's biology is cyclical, not linear. Every month has four distinct hormonal seasons — each unlocking different cognitive, emotional, and physical capabilities. HerCycle reads your biometrics and tells you which season you're in, then takes action accordingly.910## The Four Seasons1112| Season | Phase | Days | What's Amplified |13|--------|-------|------|-----------------|14| 🌑 Winter | Menstrual | 1–5 | Introspection, pattern recognition, deep insight, rest & recovery |15| 🌱 Spring | Follicular | 6–14 | Creativity, optimism, new ideas, social energy, starting things |16| ☀️ Summer | Ovulation | ~14 | Communication, charisma, negotiation, peak performance, visibility |17| 🍂 Autumn | Luteal | 15–28 | Detail orientation, completion, editing, boundaries, deep focus |1819## Data Sources2021HerCycle reads from:22- **Whoop API** — HRV, recovery score, sleep quality, skin temperature (ovulation signal)23- **Cycle tracking** — stored in WhoopClaw DB (`cycle_tracking` table), or inferred from skin temp patterns24- **Phase inference** — if no explicit cycle log, estimate phase from skin temp trend + HRV patterns2526See `references/whoop-api.md` for data access patterns.2728## Action Modules2930Actions are pluggable. Each module takes the current phase + biometrics and returns a recommendation or triggers an action.3132Current modules:33- **🎵 Music** — Spotify mood matching via a phase-aware playlist engine (see your WhoopClaw `spotify_engine.py` or bring your own)34- **💪 Training** — Push hard (follicular/ovulation) vs restore (menstrual/luteal)35- **🥗 Nutrition** — Iron-rich (menstrual), protein/carb cycling (luteal), light & fresh (ovulation)36- **📅 Calendar** — Phase-aware scheduling nudges (big meetings → ovulation, deep work → luteal)37- **💬 Social** — Energy level signal ("high charisma window" vs "protect your bandwidth")3839To add a new action module: see `references/action-modules.md`.4041## Usage4243**Check current phase:**44> "What phase am I in?" / "What's my cycle season today?"4546**Phase-aware recommendation:**47> "Should I push hard at the gym today?"48> "What should I eat this week?"49> "Is this a good week for a big presentation?"5051**Trigger an action:**52> "Play music for my phase" / "Give me a playlist for my cycle phase"5354## Setup Requirements5556HerCycle requires a running WhoopClaw instance — an open-source FastAPI backend that handles Whoop OAuth, cycle tracking, and biometric storage. Search GitHub for "WhoopClaw" to find an implementation, or build your own against the Whoop Developer API.5758**Prerequisites:**591. **Whoop API credentials** — register at [developer-dashboard.whoop.com](https://developer-dashboard.whoop.com) to get your `WHOOP_CLIENT_ID` and `WHOOP_CLIENT_SECRET`602. **WhoopClaw running locally** — clone, configure `.env`, and start the server (`uvicorn main:app`)613. **Whoop account connected** — complete the OAuth flow via WhoopClaw's `/whoop/authorize` endpoint6263Once running, configure `WHOOPLAW_BASE_URL` to point to your instance (default: `http://localhost:8000`).6465Key endpoints HerCycle uses:66- `GET /whoop/recovery` — latest recovery + HRV67- `GET /cycle/current-phase?telegram_id=<id>` — current cycle phase68- `GET /cycle/predictions?telegram_id=<id>` — next period prediction69- `GET /whoop/metrics/skin-temp` — skin temperature trend (ovulation signal)7071Always pull live data before making recommendations. Do not rely on stale cached values.7273## Philosophy7475> *"Every month I experience four seasons... in this season, certain sensitivity and capacity is amplified."* — Chloé Zhao, Oscar-winning director (BBC 100 Women)7677The goal is not to manage around the cycle. It's to move with it — scheduling, eating, training, socialising, and creating in alignment with what's naturally amplified. The cycle is the intelligence. HerCycle makes it legible.
dvcrn