Hevy

Hevy Fitness Tracking

Integrate with Hevy app for comprehensive fitness tracking, workout analysis, and progress monitoring.

Prerequisites

• Hevy Pro subscription (required for API access)
• API key from Hevy Developer Settings

Quick Start

1. Install hevycli

./scripts/install_hevycli.sh

2. Configure API Key

./scripts/configure_api.sh YOUR_API_KEY

3. Test Installation

hevycli workout count --output json

Core Operations

Workout Tracking

List recent workouts:

hevycli workout list --since 2026-02-01 --output json

Get specific workout details:

hevycli workout get <workout-id> --output json

Get workout count:

hevycli workout count --output json

Progress Analysis

Track exercise progression:

hevycli stats progress "Bench Press" --output json
hevycli stats progress "Squat" --metric 1rm --output json

Get workout summaries:

hevycli stats summary --period month --output json
hevycli stats summary --period week --output json

View personal records:

hevycli stats records --output json
hevycli stats records --exercise "Bench Press" --output json

Exercise Management

Search for exercises:

hevycli exercise search "bench" --output json

List exercise templates:

hevycli exercise list --output json

Routine Management

List routines:

hevycli routine list --output json

Get routine details:

hevycli routine get <routine-id> --output json

Convenience Scripts

Recent Activity Analysis

# Last 7 days of workouts
./scripts/get_recent_workouts.sh 7 json

# Last 30 days
./scripts/get_recent_workouts.sh 30 json

Progress Tracking

# Weight progression
./scripts/track_progress.sh "Bench Press" weight json

# Estimated 1RM progression  
./scripts/track_progress.sh "Deadlift" 1rm json

Statistics Overview

# Monthly stats with records
./scripts/get_stats.sh month json

# Weekly overview
./scripts/get_stats.sh week json

Integration Patterns

Body Status Tracking

Daily workout summary:

# Check if workout completed today
TODAY=$(date +%Y-%m-%d)
hevycli workout list --since $TODAY --output json | jq '.[] | {title, duration_minutes: (.end_time | fromdate) - (.start_time | fromdate) | . / 60}'

Weekly volume analysis:

WEEK_AGO=$(date -d '7 days ago' +%Y-%m-%d)
hevycli workout list --since $WEEK_AGO --output json | jq 'map(.exercises[].sets | map(.weight_kg * .reps) | add) | add'

Progress toward goals:

# Track specific lift PRs
hevycli stats records --exercise "Bench Press" --output json | jq '.records[0].weight_kg'

RPG Integration

Each workout can be treated as a quest with XP based on:

• Volume: Total weight lifted
• Duration: Time spent training
• Consistency: Streak tracking via workout frequency
• Progress: PRs and strength gains

XP Calculation Example:

# Get today's workout volume for XP calculation
hevycli workout list --since $(date +%Y-%m-%d) --output json | \
jq '[.[].exercises[].sets[] | (.weight_kg // 0) * (.reps // 0)] | add // 0'

Data Formats

All commands support --output json for structured agent consumption. See references/data_structures.md for complete JSON schema examples.

Key Fields

• Workouts: id, title, start_time, end_time, exercises, notes
• Exercises: title, muscle_groups, sets (weight_kg, reps, rpe)
• Stats: total_workouts, total_volume_kg, average_duration_minutes
• Records: exercise, weight_kg, reps, date, estimated_1rm_kg

Configuration

Config file location: ~/.hevycli/config.yaml

Recommended agent settings:

api:
  key: "your-api-key"
display:
  output_format: json
  color: false
  units: metric

Troubleshooting

API Issues

• 401 Unauthorized: Check API key and Hevy Pro subscription
• Rate Limiting: Hevy API has rate limits - space out requests
• Network Errors: Check internet connection

Installation Issues

• Binary not found: Ensure ~/.local/bin is in PATH
• Permission errors: Make scripts executable: chmod +x scripts/*.sh

References

• Command Reference: references/api_commands.md - Complete CLI command guide
• Data Structures: references/data_structures.md - JSON schemas and examples
• Hevy API Docs: https://api.hevyapp.com/docs/
• Hevy App: https://www.hevyapp.com/

Security Notes

• API key stored in ~/.hevycli/config.yaml or env variable HEVY_API_KEY
• Ensure proper file permissions (600) on config file
• Never commit API keys to version control
• API key provides read/write access to all Hevy data