Runstr analytics

Advanced RUNSTR fitness analytics with trend analysis, performance insights, training recommendations, and correlation tracking. Analyzes workout history, ha...

RUNSTR Analytics Skill

Advanced fitness analytics and coaching insights for RUNSTR data. Provides trend analysis, performance tracking, habit correlation, and personalized training recommendations.

Setup

Required: RUNSTR_NSEC environment variable

This skill requires your Nostr private key (nsec1...) to decrypt RUNSTR backup data.

Option 1 - For OpenClaw/chat usage: Tell your bot: "Here's my RUNSTR nsec: nsec1..."

Option 2 - For CLI/cron automation:

export RUNSTR_NSEC="nsec1..."

⚠️ Security note: The nsec is passed securely via stdin (not CLI arguments) to prevent exposure in process lists. Cache files use restrictive permissions (0700/0600).

---

Features

• Advanced Trend Analysis: Pace trends by activity type, seasonal comparisons, training load tracking
• Performance Insights: Personal records, weekly challenges, streak tracking
• Correlation Analysis: Mood vs training, habits vs performance, sleep vs recovery
• Training Recommendations: AI-driven tips for improvement, goal-based planning
• Training Plan Integration: Sync with external training plans, track adherence

Quick Start

Extended version (recommended - with local cache):

# First run - fetch from Nostr and cache locally
python3 scripts/analyze_extended.py --nsec <NSEC> --days 60 --insights --force-refresh

# Subsequent runs - use cached data (no nsec needed!)
python3 scripts/analyze_extended.py --days 60 --insights

Lightweight version (basic analysis):

python3 scripts/analyze_light.py --nsec <NSEC> --days 30 --insights

Full version (requires pandas, numpy, scipy):

# Install dependencies first: pip3 install pandas numpy scipy
python3 scripts/analyze.py --nsec <NSEC> --days 60 --coaching-report

Commands

Flag	Description
--nsec	Your Nostr private key (nsec1...)
--days	Analysis period (default: 30)
--insights	Generate improvement tips
--coaching-report	Full coaching analysis
--training-plan	Path to training plan markdown file
--trends	Show trend visualizations
--correlations	Analyze habit/mood correlations
--pb	Show personal records
--challenges	Generate weekly challenges

Data Sources

1. Nostr Encrypted Backup (Kind 30078): Primary workout, habit, journal data
2. Local Cache: SQLite database for fast re-analysis
3. Training Plans: Markdown files with structured training schedules

Extended Features (analyze_extended.py)

Local Cache

• SQLite database stores workouts locally
• Fast subsequent analyses (no Nostr query needed)
• Automatic PR tracking across sessions
• Cache location: ~/.cache/runstr-analytics/

Week-to-Week Comparison

# Shows last 4 weeks with trends
python3 scripts/analyze_extended.py --insights

Personal Records

• Automatically detects PRs for: 1K, 5K, 10K, Half Marathon
• Stores historical PRs in cache
• Shows date and pace for each PR

Visual Charts

• ASCII bar charts for weekly stats
• Sparkline trend indicators (📈 📉 ➡️)
• Easy visual comparison between weeks

Automated Daily Updates

# Set up daily cron job (runs at 07:00)
./setup_cron.sh

# View latest automated report
./view_report.sh

# Check update logs
tail -f ~/.cache/runstr-analytics/daily_update.log

The automation will:

• Check if cache is older than 12 hours
• Fetch fresh data from Nostr if needed
• Generate new report with charts
• Save to ~/.cache/runstr-analytics/latest_report.txt

Usage Examples

# First time setup - fetch and cache
python3 scripts/analyze_extended.py --nsec nsec1... --force-refresh

# Daily check - uses cache
python3 scripts/analyze_extended.py --insights

# Analyze last 90 days
python3 scripts/analyze_extended.py --days 90 --insights

# Force re-fetch from Nostr (after new backup)
python3 scripts/analyze_extended.py --nsec nsec1... --force-refresh

# Set up automatic daily updates
./setup_cron.sh

# View today's automated report
./view_report.sh

Analytics Engine

Trend Calculations

• Rolling averages (7-day, 30-day)
• Week-over-week comparisons
• Pace progression by distance bracket
• Training load (acute vs chronic)

Correlation Analysis

• Pearson correlation for numeric relationships
• Mood distribution by activity type
• Habit impact on performance metrics

Recommendation Engine

• Rule-based coaching tips
• Goal gap analysis
• Recovery recommendations

Output Formats

• Terminal tables (default)
• JSON export (--format json)
• Markdown reports (--format md)

Security Considerations

Private Key Handling

• RUNSTR_NSEC is your Nostr private key — treat it like a password. Never share it.
• This skill passes the key via stdin (not command-line arguments) to prevent exposure in process lists (ps)
• For added security on multi-user systems, ensure your system is not configured to log environment variables

Local Data Protection

• Decrypted workout/journal data is cached locally in ~/.cache/runstr-analytics/runstr_cache.db
• Cache directory and database files are created with restrictive permissions (0700/0600) — only your user can access them
• Ensure your disk is encrypted (full-disk encryption) for maximum protection

Recommended Installation

• Install on a personal machine with restricted access (single user, disk encryption enabled)
• Consider pinning the nak binary to a specific release rather than using @latest
• Review the cron setup before enabling automatic daily updates

Privacy

• NSEC is never stored or logged in skill output
• All processing happens locally on your machine
• Nostr queries use encrypted connections (WSS/WebSocket Secure)
• No data is sent to external analytics services