workout-claw

Local-first gym workout tracker. Plain-JSON storage at ~/.workout-claw/. Invokable as a CLI by an agent — no MCP server, no daemon.

Setup

This skill ships a SKILL.md manifest via ClawHub, but the workout-claw CLI binary lives on npm. Both layers are required.

openclaw skills install workout-claw    # installs this SKILL.md
npm install -g workout-claw             # installs the CLI binary

Requires Node >= 20. Once both are installed, the CLI is on PATH and other skills can invoke it.

When to invoke

User describes a workout session, asks about progress, or wants to see a PR. Examples that should trigger this skill:

• "I just did chest day — bench 4x10 at 60, incline DB 4x12 at 20, triceps 4x12 at 40"
• "Log today's workout"
• "What's my bench PR?"
• "Show my back workouts from the last 4 weeks"
• "What did I do at the gym today?"

How to invoke

Use the workout-claw CLI via Bash. All commands output YAML to stdout, errors to stderr.

Log a workout

workout-claw log "bench 4x10@60, incline-db-press 4x12@20, triceps-pushdown 4x12@40"

Optional flags:

• --muscle <group> — back | legs | chest | shoulders | arms | core | full | cardio | other. If omitted, inferred from the exercises (most sets wins; a tie is full; cardio-only is cardio), unless the user has an optional ~/.workout-claw/config.json weekday split ({"split":{"mon":"back","wed":"legs"}}), which then applies on those days.
• --cardio "<entry>" — e.g. "incline-walk 20min @4.5kmh i6" (minutes, speed kmh, incline)
• --note "<text>" — free-text note
• --date YYYY-MM-DD — date to log under (default: today in local time). Pass it explicitly when the user logs a past session or it is just after midnight. Anything that is not a real date is rejected.
• --time HH:MM — override time

Input syntax

<exercise> <sets>x<reps>@<weight> per entry, comma-separated for multiple exercises. Also accepted: a kg/lb suffix (bench 3x8@60kg, lb is stored as kg), spaces in names (bench press 3x8@60), and uneven sets: bench 8,8,6@60 (per-set reps, one weight) or bench 8@60,6@65 (per-set reps and weights).

• Multi-word exercise names use dashes: incline-db-press, barbell-row
• Bodyweight: pullups 4x10@bw
• All weights in kg

Query history

workout-claw history --muscle chest --weeks 4
workout-claw history --exercise bench

Get a PR

workout-claw pr bench

Returns best estimated 1RM via Epley formula: weight × (1 + reps/30).

Cross-day muscle volume (v0.3+)

workout-claw volume --muscle back --weeks 4
workout-claw volume --muscle chest --weeks 8

Aggregates volume per exercise, not per session. Pullups on chest day count toward back volume; triceps-pushdown counts toward arms. Returns total kg lifted, sets, reps, days trained, and a per-date breakdown.

This is the right query for tracking weekly volume per muscle group — far more accurate than history --muscle X which is session-grain.

Summary of today

workout-claw summary
workout-claw summary --date 2026-05-15

Most recent session

workout-claw last

Returns the latest session across all dates — useful for "what did I do at the gym?" without naming a date.

Delete a session

workout-claw delete <session-id>

Session IDs come from the id field in any log / summary / last output. No confirmation prompt — the CLI is non-interactive by design.

Edit a session

workout-claw edit <session-id>

Opens the session JSON in $EDITOR (defaults to vi). On save: validates JSON, refuses to save if the id was changed. On parse error: original session unchanged. Useful for fixing typos in exercise names or set counts without a full delete + re-log.

Agent note: edit requires an interactive editor, so the agent should not invoke this in a Telegram round-trip. Instead, when a user asks to fix a logged workout via Telegram, prefer delete + log again, or hand back the session ID and tell the user to run workout-claw edit <id> from their terminal.

Data location

• ~/.workout-claw/logs/<date>.json — one JSON file per day, array of sessions
• Schema: see src/lib/types.ts in the workout-claw repo

Notes for the agent

• After logging, relay the YAML summary back to the user in a readable form (don't dump raw YAML)
• Exercise names may contain spaces or dashes (stored with dashes), so pass the user's wording through ("incline DB press" → incline-db-press)
• If the CLI reports corrupt JSON, stop and tell the user: the file is left untouched, and nothing was logged. Do not retry or recreate it.
• Session-level --muscle is inferred from the exercises — only set explicitly if the user names a split that differs from what was lifted. Per-exercise muscle tags are inferred automatically at log time via name lookup (pullups→back, bench→chest, etc.), so no extra input is needed.
• When user describes cardio separately, use --cardio flag. When they describe both lifting + cardio in one breath, use both.
• For "how much back/chest/leg volume?" questions, prefer volume --muscle X over history --muscle X — volume aggregates per-exercise, history filters per-session.