Claw Coach

Name: Claw Coach
Rating: 3.5 (1 reviews)
Author: xiongyecpu

By xiongyecpu 👁 65 views ▲ 0 votes

AI Running Coach - OpenClaw/Hermes Skill plugin for personalized running training plans

GitHub

Configuration Example

# ~/.hermes/config.yaml
mcp_servers:
  coros:
    command: "npx"
    args: ["-y", "coros-mcp"]
    env:
      COROS_EMAIL: "your-email"
      COROS_PASSWORD: "your-password"
    allowed_tools:
      - "authenticate_coros"
      - "get_daily_metrics"
      - "list_activities"
      - "get_activity_detail"
      - "create_workout"  # Push to watch!

README

# AI Running Coach 🏃

> **English** | [中文](README.zh.md)

An AI-powered running coach Skill for [OpenClaw](https://github.com/openclaw/openclaw) and [Hermes Agent](https://github.com/nousresearch/hermes).

Connect your running data, match with a science-based virtual coach, and get personalized training plans.

## Features

- **Dual-platform**: Compatible with both OpenClaw and Hermes Agent
- **Multi-data-source**: Strava API + COROS (direct API / MCP protocol)
- **3 Virtual Coaches**: Daniels VDOT, Hansons Marathon Method, MAF 180
- **AI Recommendation**: Multi-dimensional scoring to match the best coach for you
- **Dynamic Adjustment**: Auto-adjusts upcoming plans based on execution feedback
- **Safety First**: ACWR monitoring, overtraining detection, injury-aware routing
- **Visualization**: Beautiful HTML charts for training analytics

## Quick Start

### OpenClaw Installation

```bash
git clone https://github.com/xiongyecpu/claw-coach.git ~/.openclaw/skills/running-coach
cd ~/.openclaw/skills/running-coach
cp config.example.json config.json
# Edit config.json with your API credentials
```

### Hermes Agent Installation

```bash
git clone https://github.com/xiongyecpu/claw-coach.git ~/.hermes/skills/running-coach
cd ~/.hermes/skills/running-coach
cp config.example.json config.json
# Edit config.json with your API credentials

# Optional: configure COROS MCP Server
hermes mcp add coros --command "npx" --args "-y","coros-mcp"
```

Then talk to your Agent: **"I want to start running training"**

## Coaching Team

| Coach | Methodology | Best For | Weekly Volume |
|-------|-------------|----------|---------------|
| 🎓 Jack (VDOT) | Daniels VDOT Formula | Race goals, data-driven runners | 15-100km |
| 🏃 Hanson | Hansons Marathon Method | Marathon training | 30-90km |
| 💚 Phil (MAF) | MAF 180 Method | Beginners, injury recovery, health-focused | 0-60km |

## Data Sources

| Platform | Auth | Data Types | Highlights |
|----------|------|------------|------------|
| **Strava** | OAuth 2.0 / Access Token | Activities, GPS, HR, Power, Cadence | Largest running community |
| **COROS** | Email + Password (MD5) | Activities, HR, HRV, Sleep, Training Load | **Push workouts to watch** |

### COROS MCP Integration

Hermes users can access COROS data via MCP protocol:

```yaml
# ~/.hermes/config.yaml
mcp_servers:
  coros:
    command: "npx"
    args: ["-y", "coros-mcp"]
    env:
      COROS_EMAIL: "your-email"
      COROS_PASSWORD: "your-password"
    allowed_tools:
      - "authenticate_coros"
      - "get_daily_metrics"
      - "list_activities"
      - "get_activity_detail"
      - "create_workout"  # Push to watch!
```

## Recommendation Decision Tree

```
Are you a beginner (< 1 year running)?
  → Coach Phil (MAF) ✅

Are you recovering from injury?
  → Coach Phil (MAF) ✅

Weekly mileage < 30km?
  → Coach Phil (MAF) or Coach Jack (reduced)

Weekly mileage 30-60km?
  → Coach Jack (VDOT) ✅ or Coach Hanson

Weekly mileage > 60km?
  → Coach Hanson ✅ or Coach Jack

Goal is 5K/10K?
  → Coach Jack (VDOT) ✅

Goal is half-marathon?
  → Coach Jack (VDOT) ✅ or Coach Hanson

Goal is first marathon?
  → Coach Hanson ✅

Goal is marathon PB?
  → Coach Hanson ✅ or Coach Jack

Pursuing health / no race goal?
  → Coach Phil (MAF) ✅
```

## Training Safety

⚠️ **Disclaimer**: This Skill provides training suggestions, not medical advice. Consult a doctor before starting any new training program, especially if you have heart disease, high blood pressure, diabetes, or other chronic conditions.

Built-in safety mechanisms:
- ACWR monitoring (Acute:Chronic Workload Ratio), warns when > 1.5
- Weekly volume increase capped at 10%
- Automatic low-intensity coach recommendation when injury history is present
- All high-intensity recommendations include warm-up and cool-down

## Interaction Examples

### First Use
```
User: I want to start running training
AI: Welcome! I'm your AI Running Coach 🏃
    Let me learn about you first:
    1. How many km do you run per week?
    2. What's your running goal? (health/5K/10K/half/full)
    3. Do you have a sports watch? (Strava/COROS/other)

User: 20km/week, half-marathon goal, COROS
AI: Great! Let me connect your COROS data and analyze...
    [Syncing data...]
    [Analysis complete]

    Based on your data, I recommend:
    1. Coach Jack (VDOT) — Match score: 85
       Reason: Your volume and goal fit VDOT methodology perfectly
    2. Coach Hanson — Match score: 72
    3. Coach Phil (MAF) — Match score: 60

    Which coach would you like to choose?
```

### Daily Training
```
User: What should I train today?
AI: According to Coach Jack's plan, today's (Tuesday) workout is:
    🔴 Interval: 5x1km @ 4:15/km
    Rest: 3min easy jog
    Warm-up: 15min easy run
    Cool-down: 10min easy run
    Estimated total: 55min
```

## Project Structure

```
running-coach/
├── SKILL.md                    # Skill manifest (dual-platform)
├── README.md                   # English docs
├── README.zh.md                # Chinese docs
├── LICENSE                     # Apache-2.0 License
├── config.example.json         # Config template
├── install.sh                  # Install script
├── .github/                    # GitHub templates
│   └── ISSUE_TEMPLATE/
├── references/                 # Knowledge base
│   ├── training_methods/
│   │   ├── daniels_vdot.md     # Daniels VDOT deep dive
│   │   ├── hansons.md          # Hansons Marathon Method
│   │   └── maf180.md           # MAF180 deep dive
│   └── coach_profiles.md       # Coach profiles summary
└── scripts/
    ├── data/                   # Data layer
    │   ├── base_adapter.py
    │   ├── strava_adapter.py
    │   ├── coros_adapter.py
    │   └── unified_model.py
    ├── coaches/                # Coach engines
    │   ├── base_coach.py
    │   ├── coach_daniels.py
    │   ├── coach_hanson.py
    │   └── coach_maf.py
    ├── engine/                 # Recommendation engine
    │   ├── analyzer.py
    │   ├── recommender.py
    │   └── plan_generator.py
    └── visualization/
        └── charts.py
```

## Roadmap

### V1 (Current) — MVP
- [x] Strava data integration
- [x] 3 core coaches (Daniels / Hanson / MAF)
- [x] Basic recommendation engine
- [x] Weekly training plan generation
- [x] ACWR + overtraining detection
- [x] Training visualization charts

### V2 — Multi-source + Expansion
- [ ] COROS MCP protocol integration
- [ ] Garmin Connect adapter
- [ ] 4 new coaches (Canova dual threshold / 80-20 / Lydiard / Polarized)
- [ ] Push training plans to watch
- [ ] Data persistence (SQLite)

### V3 — Full Feature
- [ ] 10 coaches total
- [ ] Altitude training scenarios
- [ ] Social features (training sharing)
- [ ] Multi-language support
- [ ] Nutrition & recovery advice

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). We welcome:
- New coaches (polarized, Lydiard, Canova dual threshold, etc.)
- New data sources (Garmin, Apple Health, Suunto)
- Bug reports and feature requests
- Documentation improvements

## License

Apache License 2.0 — see [LICENSE](LICENSE).

tools