# How to Add Whoop Metrics Integration to Zakirullin Files Journals

> Integrate Whoop metrics into Zakirullin Files journals using the Go utility. Convert CSV exports to Markdown and analyze sleep, recovery, and workout data effortlessly.

- Repository: [Artem Zakirullin/files.md](https://github.com/zakirullin/files.md)
- Tags: how-to-guide
- Published: 2026-05-21

---

**Zakirullin Files includes a standalone Go utility in [`cmd/whoop/whoop.go`](https://github.com/zakirullin/files.md/blob/main/cmd/whoop/whoop.go) that converts raw Whoop CSV exports into formatted Markdown journal entries, processing sleep, recovery, and workout data for the last 10 days.**

The zakirullin/files.md repository provides a minimalist journaling system based on plain Markdown files. For users tracking biometric data, the repository ships with a purpose-built **Whoop metrics integration** that transforms CSV exports from the Whoop dashboard into human-readable journal entries without requiring API access or internet connectivity.

## How the Whoop Integration Works

The utility operates entirely offline by parsing three specific CSV files exported from the Whoop dashboard.

### Entry Point and Data Structure

The `main()` function in [`cmd/whoop/whoop.go`](https://github.com/zakirullin/files.md/blob/main/cmd/whoop/whoop.go) accepts a path to the export folder (defaulting to the current directory `.`) and initializes a map of `day` structs keyed by date. Each struct aggregates metrics from sleep, recovery, and workout sources into a single chronological record.

### Parsing the Whoop CSV Files

Three dedicated functions handle the distinct data types:

- **`parseSleeps()`** reads `sleeps.csv` and extracts sleep performance percentage, total minutes asleep, and a presence flag.
- **`parseCycles()`** processes `physiological_cycles.csv` to capture recovery score, heart rate variability (HRV), resting heart rate (RHR), and strain metrics.
- **`parseWorkouts()`** handles `workouts.csv`, storing each activity type with its duration.

All parsers utilize generic CSV helpers—`readCSV()`, `indexHeader()`, `field()`, `parseTime()`, `atoi()`, and `atof()`—to safely manage missing columns and string-encoded numeric values.

### Sorting and Filtering

After parsing, the utility sorts the collected days in **descending chronological order** using `sort.Slice` with `Date.After`. The output is deliberately limited to the **last 10 days** to maintain concise weekly or bi-weekly journal reviews.

### Markdown Rendering

The `printDay()` function generates a structured Markdown block for each date:

```markdown
#### 23 July, Thursday

- Sleep: 86%, 7h 12m
- Recovery: 94%, HRV 61, RHR 52
- Strain: 3.2
- Workout: Run 45m
- Workout: Yoga 30m

```

This format is optimized for direct insertion into journal files such as `journal/2024.08 August.md`.

## Running the Whoop Metrics Integration

To generate journal entries from your Whoop export:

```bash

# Export your Whoop data to a folder, e.g. ~/whoop-export

go run ./cmd/whoop/whoop.go ~/whoop-export

```

### Appending to Monthly Journals

For automated insertion into a monthly journal file:

```bash
go run ./cmd/whoop/whoop.go ~/whoop-export >> journal/$(date +%Y.%m).md

```

### Advanced Scripting

Insert the output under a specific heading using `sed`:

```bash
#!/usr/bin/env bash
EXPORT_DIR="${1:-$HOME/whoop}"
OUTPUT="$(go run ./cmd/whoop/whoop.go "$EXPORT_DIR")"
sed -i "/^## Whoop metrics$/a $OUTPUT" journal/$(date +%Y.%m).md

```

## Summary

- The **Whoop metrics integration** resides in [`cmd/whoop/whoop.go`](https://github.com/zakirullin/files.md/blob/main/cmd/whoop/whoop.go) and requires no API keys or network access.
- It parses three CSV files—`sleeps.csv`, `physiological_cycles.csv`, and `workouts.csv`—using robust helper functions.
- Output is sorted by date descending and limited to the **last 10 days** for readability.
- The generated Markdown is compatible with any file in the Zakirullin Files journal structure.

## Frequently Asked Questions

### Does the Whoop integration require an API subscription?

No. The utility reads local CSV files exported from the Whoop dashboard, making it completely offline and API-independent as implemented in zakirullin/files.md.

### Can I modify the number of days included in the output?

Yes. The limit is hardcoded in the `main()` function loop (currently set to 10). You can adjust this value in [`cmd/whoop/whoop.go`](https://github.com/zakirullin/files.md/blob/main/cmd/whoop/whoop.go) before running the tool to show more or fewer days.

### What happens if my Whoop export is missing a CSV file?

The parser safely handles missing columns and files through defensive programming in helpers like `field()` and `atof()`. Missing data simply results in omitted metrics for that day rather than parser errors.

### Is the output compatible with other journaling systems?

Yes. Because the tool outputs pure Markdown, you can integrate the results into any text-based journal system, not just Zakirullin Files.