trainer: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

trAIner is an open-source agentic AI personal trainer for fitness and health, built with Google ADK (Gemini) and powered by Strava data through MCP (Model Context Protocol).

Technology Stack

• Language: Python 3.13+
• AI Framework: Google ADK (google-genai)
• Integration: Strava MCP Server
• Data Validation: Pydantic v2
• Testing: pytest with async support
• Code Quality: ruff (linter/formatter), mypy (type checking)
• Build System: Hatchling

Commands

Development Setup

# Install package in editable mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

# Set up Strava MCP Server
git clone https://github.com/r-huijts/strava-mcp.git
cd strava-mcp
npm install
npm run build
npx tsx scripts/setup-auth.ts  # Follow prompts to authenticate with Strava

# Set up environment
cp .env.example .env
# Edit .env to add:
# - GEMINI_API_KEY: Your Google Gemini API key
# - STRAVA_MCP_PATH: Absolute path to strava-mcp/dist/server.js

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=trainer --cov-report=html

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration

# Run specific test file
pytest tests/unit/test_formatters.py

Code Quality

# Lint and check code
ruff check .

# Format code
ruff format .

# Type checking
mypy src/trainer

Architecture

Core Components

1. Agents (src/trainer/agents/)

   • TrainerAgent: Main agentic AI trainer using Google ADK
   • Handles workout analysis, training plan generation, and conversational coaching
   • Integrates with Strava MCP tool for activity data

2. Models (src/trainer/models/)

   • Workout: Represents Strava activity data
   • WorkoutAnalysis: Structured analysis output with recommendations
   • TrainingPlan: Multi-week training plan structure
   • All models use Pydantic for validation