hevy-hermes-agent-skill

Hevy Hermes Agent Skill — Workout Analysis & Routine Automation

A reusable Hermes Agent skill and dependency-free Python CLI for safe Hevy Public API workout analysis, routine management, webhook processing, and fitness automation.

Features

• Read workouts, workout events, routines, exercise templates, exercise history, and body measurements
• Analyze training frequency, working sets, volume, RPE, estimated 1RM, and weekly trends
• Resolve Hevy webhook payloads containing workoutId
• Export, create, and safely update routines
• Guard every remote write with dry-run previews and explicit confirmation
• Retry safe/idempotent reads while avoiding automatic retries of non-idempotent POST requests
• Load credentials from HEVY_API_KEY or a local Hermes .env file

Repository layout

.
├── SKILL.md
├── references/
│   ├── api.md
│   └── distribution.md
└── scripts/
    ├── hevy_client.py
    └── test_hevy_client.py

Requirements

• Python 3.10+
• Hevy Pro with a Public API key
• No third-party Python packages

Credential setup

Never commit the API key. Put it in the active Hermes environment file:

HEVY_API_KEY=your-key-here

The CLI checks the process environment and common Hermes .env locations.

Install as a Hermes skill

Install directly from the public SKILL.md. Hermes also retrieves the explicitly referenced files under scripts/ and references/:

hermes skills install https://raw.githubusercontent.com/lazyperfectionist/hevy-hermes-agent-skill/main/SKILL.md

Alternatively, clone the complete repository:

git clone https://github.com/lazyperfectionist/hevy-hermes-agent-skill.git
cp -R hevy-hermes-agent-skill ~/.hermes/skills/productivity/hevy-workout-operations

On Windows Hermes Desktop, the active skill directory is commonly under:

%LOCALAPPDATA%\hermes\skills\productivity\hevy-workout-operations

CLI examples

From the repository root:

python scripts/hevy_client.py status
python scripts/hevy_client.py workouts --all
python scripts/hevy_client.py routines --all
python scripts/hevy_client.py analyze --days 90 --with-muscles
python scripts/hevy_client.py webhook --json '{"workoutId":"<id>"}'

Safe routine update

# Export the current full routine payload
python scripts/hevy_client.py routine-export <routine-id> --out routine.json

# Preview only
python scripts/hevy_client.py routine-update <routine-id> --file patch.json

# Apply only after reviewing the diff
python scripts/hevy_client.py routine-update <routine-id> \
  --file patch.json --apply --confirm <routine-id>

Safe routine creation

# Preview
python scripts/hevy_client.py routine-create --file new-routine.json

# Apply
python scripts/hevy_client.py routine-create \
  --file new-routine.json --apply --confirm CREATE

Tests

python -m py_compile scripts/hevy_client.py scripts/test_hevy_client.py
python scripts/test_hevy_client.py -v

Tests do not require a real API key and do not write to Hevy.

API caveat

Hevy currently describes its Public API as an early, changeable interface. The included reference was checked against OpenAPI document version 0.0.1. Re-check the official documentation if a response shape changes.

License

MIT