How to Add Whoop Metrics Integration to Zakirullin Files Journals

Zakirullin Files includes a standalone Go utility in 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 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:

#### 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:

# 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:

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

Advanced Scripting

Insert the output under a specific heading using sed:

#!/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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}