lift-tracker 0.5.0

A robust feature-complete CLI for tracking weightlifting sessions with a focus on bodybuilding

🏋️ LIFT - Bodybuilding Workout Tracker

A robust, feature-complete command-line interface for tracking weightlifting sessions with a focus on bodybuilding and progressive overload.

Features

📝 Comprehensive Exercise Library

• 137 pre-loaded exercises covering all major muscle groups
• Organized by category (Push, Pull, Legs, Core)
• Classified by movement type (Compound vs Isolation)
• Multiple equipment types (Barbell, Dumbbell, Cable, Machine, Bodyweight)
• Add custom exercises
• Search and filter by muscle group, category, or equipment

💪 Workout Tracking

• Interactive workout sessions with beautiful terminal UI
• Real-time set logging with shortcuts (s=same, +5=add weight)
• Track weight, reps, RPE (Rate of Perceived Exertion)
• Optional tempo tracking
• View last performance for each exercise
• Automatic volume calculations
• Workout history and summaries

📋 Training Programs

• Create custom training programs with splits
• Pre-loaded sample programs:
  • PPL 6-Day (Push/Pull/Legs)
  • Upper/Lower 4-Day
  • Full Body 3-Day
• Workout templates with exercise prescriptions
• Set target sets, reps ranges, RPE, and rest periods
• Clone and modify existing programs
• Track program adherence

📊 Analytics & Statistics

• Automatic PR detection (1RM, 3RM, 5RM, 10RM, volume PRs)
• Exercise progression tracking
• Volume analysis by muscle group
• Weekly/monthly training summaries
• Training consistency streaks
• Terminal-based charts and visualizations
• Progressive overload recommendations
• Fatigue monitoring

📏 Body Tracking

• Bodyweight logging with trend analysis
• Comprehensive body measurements (circumferences)
• Body fat percentage tracking
• Progress comparisons (week-over-week, month-over-month)
• Measurement history and trends
• Weight charts and analytics

💾 Data Management

• Export to CSV or JSON
• Import data from other sources
• Database backup and restore
• Configuration management
• Data optimization tools

🤖 AI Assistant Integration (MCP Server)

• Claude Desktop integration via Model Context Protocol
• Natural language workout tracking and analysis
• AI-powered exercise recommendations
• Intelligent progression analysis
• Conversational data queries
• See MCP Server Documentation for setup

Installation

Requirements

• Python 3.11 or higher

Install from PyPI (Recommended)

# Standard installation
pip install lift-tracker

# With MCP server support for Claude Desktop
pip install lift-tracker[mcp]

Install with Homebrew (macOS/Linux)

# Download the formula
curl -O https://github.com/parkerdgabel/lift/releases/latest/download/lift.rb

# Install
brew install ./lift.rb

Install on Debian/Ubuntu

# Download the .deb package
wget https://github.com/parkerdgabel/lift/releases/latest/download/lift_0.1.0-1_all.deb

# Install
sudo dpkg -i lift_0.1.0-1_all.deb

# Install dependencies if needed
sudo apt-get install -f

Install from source

# Clone the repository
git clone https://github.com/parkerdgabel/lift.git
cd lift

# Install with pip
pip install -e .

Quick Start

1. Initialize the database

lift init

This creates the database, loads 137 exercises, and sets up default configuration.

2. Start your first workout

lift workout start

Follow the interactive prompts to log sets for your exercises.

3. View your exercises

# List all exercises
lift exercises list

# Search for exercises
lift exercises search "bench"

# Filter by muscle group
lift exercises list --muscle Chest

# Filter by category
lift exercises list --category Push

4. Import sample programs

lift program import-samples
lift program list
lift program show "PPL 6-Day"

Documentation

Man Page

LIFT includes a comprehensive man page with detailed documentation of all commands and options.

# Install the man page (required for PyPI installations)
lift install-manpage

# View the man page
man lift

# Or view directly from source
man man/lift.1

Note: When installing via PyPI (pip install lift-tracker), the man page is bundled but not automatically installed to your system. Run lift install-manpage after installation to make it available via the man command. Homebrew and Debian packages install the man page automatically.

The man page includes:

• Complete command reference
• Detailed option descriptions
• Practical examples for all features
• Configuration settings
• Database schema information
• Environment variables

MCP Server (AI Assistant Integration)

LIFT can integrate with Claude Desktop and other AI assistants via the Model Context Protocol.

# Quick setup with interactive wizard
lift mcp setup

# Or manually configure
lift mcp config >> ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Start the MCP server (usually automatic via Claude Desktop)
lift mcp start

Once configured, you can interact with your workout data naturally through Claude:

You: "Show me my recent workouts"
You: "What exercises target chest?"
You: "How is my bench press progressing?"
You: "Start a new workout called Push Day"
You: "Log my weight at 185 lbs"

See MCP Server Documentation for complete setup and usage guide.

Usage Guide

Exercise Management

# List exercises with filters
lift exercises list --category Push --equipment Barbell

# Show exercise library statistics
lift exercises stats

# Get detailed exercise info
lift exercises info "Barbell Bench Press"

# Add a custom exercise
lift exercises add

# Delete custom exercise
lift exercises delete "My Custom Exercise"

Workout Logging

# Start interactive workout session
lift workout start

# Show last workout
lift workout last

# View workout history
lift workout history --limit 10

# Delete a workout
lift workout delete <workout-id>

Interactive Workout Session

During a workout session, you can log sets using these shortcuts:

• 185 10 → 185 lbs × 10 reps
• 185 10 8.5 → 185 lbs × 10 reps @ RPE 8.5
• s → Same as previous set
• +5 → Add 5 lbs to previous weight
• -5 8 → Subtract 5 lbs, 8 reps
• done → Finish current exercise

Example session:

Exercise: bench press
Set 1 > 185 10 8
✓ 185 lbs × 10 reps @ RPE 8.0

Set 2 > s
✓ 185 lbs × 10 reps @ RPE 8.0

Set 3 > +5 8 9
✓ 190 lbs × 8 reps @ RPE 9.0

Set 4 > done

Program Management

# Create a new program (interactive)
lift program create

# List all programs
lift program list

# Show program details
lift program show "PPL 6-Day"

# Activate a program
lift program activate "PPL 6-Day"

# Clone a program
lift program clone "PPL 6-Day" "My PPL Variation"

# Delete a program
lift program delete "Old Program"

Analytics & Statistics

# Weekly summary
lift stats summary --week

# Monthly summary
lift stats summary --month

# Exercise-specific statistics
lift stats exercise "Bench Press"

# Exercise progression with chart
lift stats exercise "Squat" --chart

# Volume analysis
lift stats volume --weeks 12

# Personal records
lift stats pr
lift stats pr --exercise "Deadlift"

# Muscle group analysis
lift stats muscle Chest

# Training streak
lift stats streak

# Detailed progression
lift stats progress "Overhead Press" --chart

Body Tracking

# Log bodyweight
lift body weight 185.5

# Full body measurement entry
lift body measure

# View measurement history
lift body history

# Progress comparison
lift body progress --weeks 4

# View trends with charts
lift body chart weight --weeks 12
lift body chart waist --weeks 8

# Show latest measurement
lift body latest

Data Management

# Export data to JSON
lift data export --format json --output my_data.json

# Export specific table to CSV
lift data export --format csv --table workouts --output workouts.csv

# Import data
lift data import exercises.csv --table exercises

# Create backup
lift data backup --output ~/backups/lift_backup

# Restore from backup
lift data restore ~/backups/lift_backup

# Optimize database
lift data optimize

Configuration

# List all settings
lift config list

# Get a setting
lift config get default_weight_unit

# Set a setting
lift config set default_weight_unit kg

# Reset to defaults
lift config reset

Available settings:

• default_weight_unit - lbs or kg (default: lbs)
• default_measurement_unit - in or cm (default: in)
• enable_rpe - Enable RPE tracking (default: true)
• enable_tempo - Enable tempo tracking (default: false)
• rest_timer_default - Default rest timer in seconds (default: 90)
• auto_detect_pr - Automatically detect PRs (default: true)

Database

LIFT uses DuckDB for high-performance analytical queries. The database is stored at ~/.lift/lift.duckdb by default.

Custom database location

# Set via environment variable
export LIFT_DB_PATH=/path/to/custom/lift.duckdb
lift init

# Or specify per-command
lift --db-path /path/to/custom/lift.duckdb info

Database schema

The database includes:

• exercises - Exercise library with metadata
• workouts - Workout sessions
• sets - Individual set logs
• programs - Training programs
• program_workouts - Workout templates
• program_exercises - Exercise prescriptions
• personal_records - PR tracking
• body_measurements - Body tracking data
• settings - Configuration

Plus analytical views for efficient querying:

• workout_volume - Volume per workout
• weekly_muscle_volume - Volume by muscle group per week
• exercise_progression - Exercise history with 1RM estimates
• bodyweight_trend - Weekly bodyweight averages

Architecture

LIFT follows a clean architecture with clear separation of concerns:

lift/
├── cli/           # CLI command groups (Typer)
├── services/      # Business logic layer
├── core/          # Database and models (DuckDB, Pydantic)
├── utils/         # Utilities (calculations, formatters, charts)
└── data/          # Seed data (exercises, programs)

Technology Stack

• Typer - CLI framework with auto-completion
• Rich - Beautiful terminal output and formatting
• DuckDB - High-performance analytical database
• Pydantic - Data validation and serialization
• Plotext - Terminal-based charts and graphs
• Python 3.11+ - Modern Python with type hints

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

Setup development environment

# Clone repository
git clone https://github.com/yourusername/lift.git
cd lift

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=lift --cov-report=html

# Type checking
mypy lift

# Linting
ruff check lift

Running tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_exercise_service.py

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=lift --cov-report=term-missing

Roadmap

Future enhancements:

• Mobile companion app
• Web dashboard
• Training block periodization
• Exercise substitution recommendations
• Volume landmarks and achievements
• Social features (share programs, workouts)
• Integration with fitness trackers
• Plate calculator
• Rest timer with notifications
• Workout templates from programs
• Exercise demonstration GIFs

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with love for the bodybuilding community. Train hard, track harder! 💪

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Made with Claude Code 🤖