convez.ai
AgenteAutomaçãoAvançado
Sean-Koval

Tempo — Agente de Treinamento de Resistência

Sean-Koval/tempo

Coach de IA local-first para triathlon e endurance com raciocínio persistente

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente Claude que transforma dados de treinamento do intervals.icu em planos periodizados completos com raciocínio técnico. Armazena métricas derivadas em SQLite, versionando planos em markdown no Git e mantendo conhecimento de coaching via índice vetorial, permitindo rastreabilidade total de decisões.

Instalação

$npx convez-ai Sean-Koval/tempo

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Periodização automática de ciclos de treinamento (base, build, peak, taper)
  • Ajustes semanais baseados em aderência, wellness e carga de treino
  • Recuperação e explicação de decisões técnicas históricas com raciocínio
  • Busca semântica em conhecimento de coaching (Friel, Seiler, CTS, peer-review)

Veredito

Projeto sofisticado que resolve um problema real (falta de raciocínio persistente no intervals.icu) com stack moderno: LanceDB para semântica, SQLite para métricas, markdown versionado no Git. Excelente para atletas de endurance que querem transparência e rastreabilidade nas decisões de coaching; requer setup técnico e conhecimento de treinamento.

README

A tradução para o português deste README ainda está na fila.


Tempo turns Claude Code into a personal endurance coach for the long game — an Ironman buildup, a marathon peak, a year of base. It sits on top of intervals.icu (the source of truth for raw training data) and adds the reasoning layer: periodization methodology, plan artifacts in git, a derived-metrics store for fast queries, and a vector index for coaching knowledge and agent memory.

The problem with intervals.icu alone is that it handles data beautifully but has no reasoning memory — no "why did we cut volume in March?", no curated methodology, no retrievable coaching knowledge. Tempo owns that layer. It does not replicate intervals.icu's data model; it sits on top via MCP and adds three things the platform can't: persistent coaching context with rationale, versioned plan artifacts as git-diffable markdown, and a derived-metrics store optimized for fast agent reasoning.

Design doc / authoritative spec: take-this-project-and-temporal-tarjan.md


What it does

  • Plans periodization end-to-end. Takes a goal (a race from athlete/race-calendar.yaml or a non-race goal from athlete/goals.yaml) and drafts a full periodized plan with phase-by-phase structure and rationale.
  • Drafts a week at a time based on recent adherence, wellness, load, and active injury flags. Plans are git-versioned markdown, so every adjustment is a diff with a changelog entry.
  • Never writes to your calendar autonomously. Agent drafts → you review diff → coach push-week writes.
  • Retrieves trusted coaching knowledge (Friel, Seiler, Jeukendrup, CTS, peer-reviewed research) via semantic search. Every snippet is tagged with credibility; unvetted sources are flagged at retrieval time.
  • Remembers why. Persistent decisions table + vector memory make "why did we cut volume in March?" answerable six months later.

Architecture

Four substrates, each doing what it's best at. None of them pretends to do another's job.

ShapeStoreWhat lives hereWhy
Time-seriesSQLite data/coach.dbactivities, wellness, load, adherence, decisionsstable schema, fast aggregation, disposable
NarrativeMarkdown + YAMLplans, weeks, methodology, journalsgit-diffable; both queryable (frontmatter) and LLM-friendly (body)
SemanticLanceDB data/vectors/knowledge, memory, session libraryretrieval is concept-shaped, not field-shaped
AuditJSONL data/raw/every API response, gzipped weeklymakes the DB disposable; every derivation traceable
flowchart TB
    User(["You"]) <-->|conversation| Agent["Claude Code<br/>(coaching agent)"]

    Agent <-->|MCP| Intervals["intervals<br/>MCP"]
    Agent <-->|MCP| CoachDB["coach-db<br/>MCP"]
    Agent <-->|MCP| Strava["strava<br/>MCP"]

    Intervals <-->|read / explicit write| ICU[(intervals.icu)]
    Strava <-->|read| StravaAPI[(Strava)]

    CoachDB --> SQL[(coach.db<br/>activities · wellness · load · decisions)]
    CoachDB --> Vec[(LanceDB<br/>knowledge · memory · sessions)]

    ICU -.->|coach sync| Raw["data/raw/<br/>JSONL audit"]
    Raw -.->|derive| SQL
    Plans["plans/ (markdown)"] -.-> SQL

    Knowledge["knowledge/<br/>(markdown)"] -.->|embed on commit| Vec
    Memory["journal/ + changelogs<br/>+ decisions table"] -.->|nightly embed| Vec

    classDef user fill:#22c55e,stroke:#16a34a,color:#fff
    classDef agent fill:#cc785c,stroke:#a6573e,color:#fff
    classDef mcp fill:#6e56cf,stroke:#4f3cc0,color:#fff
    classDef external fill:#0a66c2,stroke:#074a8f,color:#fff
    classDef store fill:#1f2937,stroke:#374151,color:#fff
    classDef source fill:#f3f4f6,stroke:#9ca3af,color:#111

    class User user
    class Agent agent
    class Intervals,CoachDB,Strava mcp
    class ICU,StravaAPI external
    class SQL,Vec store
    class Raw,Plans,Knowledge,Memory source

You drive every conversation. The agent reads state through typed MCP tools and only writes to intervals.icu when you explicitly run coach push-week.

MCP servers wired (see .claude/settings.json):

  • intervals — 48 upstream tools + 2 Tempo extensions (get_week_summary, bulk_upsert_tagged_events). Fork of eddmann/intervals-icu-mcp.
  • coach-db — built here. Typed surface over coach.db + LanceDB. Nine tools: query_activities, get_load_curve, get_readiness, get_adherence, compare_plan_to_actual, search_knowledge, search_memory, find_similar_session, log_decision.
  • strava — r-huijts upstream. Segments, streams, anything intervals doesn't expose.

Quickstart

# 1. Clone with submodules
git clone --recurse-submodules <your-fork-of-this-repo> tempo
cd tempo

# 2. Credentials
cp .env.example .env
# edit .env — API_KEY / ATHLETE_ID from https://intervals.icu/settings

# 3. Submodule deps
cd mcp-servers/intervals-icu-mcp && uv sync && cd ../..

# 4. Athlete profile
$EDITOR athlete/profile.yaml     # FTP, zones, weight, thresholds
$EDITOR athlete/preferences.md   # coaching style, schedule, constraints

# 5. Declare a goal (or a race)
$EDITOR athlete/race-calendar.yaml
# OR
$EDITOR athlete/goals.yaml

# 6. Open Claude Code in this directory
#    .claude/CLAUDE.md loads automatically; intervals + coach-db MCPs are wired.

# Optional — auto-embed knowledge/ changes on commit + secret-scan staged diffs
bash scripts/install-hooks.sh

Safety

Tempo holds intervals.icu API keys, Strava tokens, and (on disk) several years of personal training and wellness data. The .env file is gitignored, but git accidents happen — a stray git add . from the wrong directory, a refactor that moves a credential into a tracked file. Defense-in-depth lives in a pre-commit hook.

# 1. Install gitleaks (one of):
#    macOS:   brew install gitleaks
#    Linux:   curl -sSfL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_8.18.4_linux_x64.tar.gz | tar -xz -C /usr/local/bin gitleaks
#    Windows: scoop install gitleaks
#    or:      go install github.com/gitleaks/gitleaks/v8@latest

# 2. Activate Tempo's hooks (covers gitleaks + bd flush + knowledge auto-embed)
bash scripts/install-hooks.sh

The hook scans only the staged diff on every git commit — fast, no historical-cleanup chore. A finding blocks the commit; rotate the credential before re-staging. Legitimate test fixtures can be allowlisted with an inline # gitleaks:allow comment or a fingerprint in .gitleaks.toml.

If gitleaks isn't on $PATH, the hook prints a one-line warning and skips — it doesn't block your commit, but it also doesn't protect you. Install it.

At this point the full coaching loop is wired. Skills, dashboards, and the weekly rhythm are all live — see build phases.


A day in the life

coach check-in              # morning wellness → intervals + coach.db
# ... train as normal; Garmin → Strava → intervals is automatic ...
coach sync                  # evening: pull activities, derive CTL/ATL/TSB

# Sunday — open Claude Code and run skills
/review-week                # post-mortem — adherence, trends, lessons
/plan-training-week         # draft next week, grounded in last week's data
# -- you review the diff --
coach push-week 2026-W18    # idempotent write to intervals calendar

Deterministic vs agentic — pick the right entry point:

Deterministic (pure scripts, no LLM)Agentic (Skill in Claude Code)
coach sync/bootstrap-plan — goal → plan structure
coach status/plan-training-week — draft a week
coach push-week <week>/review-week — post-mortem on last week
coach vectors rebuild/draft-race-plan — 4-week race countdown
coach check-in (prompted)/ingest-research — URL/PDF → corpus

Plus three dashboard slash commands rendered as HTML artifacts: /coach-dashboard-week, /coach-dashboard-macro, /coach-dashboard-decisions.


Repository layout

tempo/
├── athlete/              who Sean is right now — profile, goals, injuries, prefs
├── knowledge/            coaching corpus — methodology, nutrition, research
│   ├── sources.yaml         trusted-source registry with credibility tags
│   └── methodology/         phases.yaml, session-library.md, decision-rules.md
├── plans/<plan-id>/      plans in flight — yaml + rationale + weeks + changelog
├── journal/              YYYY-MM-DD.md daily notes & decisions
├── data/                 GITIGNORED — coach.db, vectors/, raw/, events.jsonl
├── mcp-servers/
│   ├── intervals-icu-mcp/   submodule — fork with 2 Tempo extensions
│   └── coach-db/            built here — FastMCP wrapper over SQLite + LanceDB
├── src/tempo/            the `coach` CLI package
├── scripts/              deterministic scripts (sync, derive, embed, hooks)
└── .claude/              system prompt, skills, slash commands, MCP settings

Gitignored at root: data/, .env, *.db, *.lance, .claude/settings.local.json.


Build phases

Phases are not calendar-bound. Each is independently useful; you can stop early if it's enough.

PhaseScopeStatus
0scaffold, intervals MCP wired, athlete + knowledge stubs — conversational planning worksshipped
1SQLite schema + coach sync/coach status; fast local queriesshipped
2LanceDB + knowledge corpus + auto-embed on commitshipped
3coach-db MCP — typed surface: query_activities, get_load_curve, get_readiness, get_adherence, compare_plan_to_actual, search_knowledge, search_memory, find_similar_session, log_decision. Strava wired.shipped
4bootstrap-plan, plan-training-week, review-week, morning-check-in Skills — full coaching loopshipped
5Dashboards (week / macro / decisions) as HTML artifactsshipped
6ingest-research, draft-race-plan, nutrition deep-dive (session fueling, carb-load, gut training)shipped

Design invariants

These are non-negotiable. Every commit is measured against them.

  • Intervals.icu is the source of truth for raw data. coach.db is always rebuildable from data/raw/ + plans/.
  • Writes to intervals are explicit. Agent drafts; user reviews diff; user runs coach push-week. No autonomous calendar mutations.
  • Every plan adjustment produces a changelog entry with rationale and a log_decision call. This is the coaching memory.
  • Structured where structure exists, semantic where it doesn't, narrative where neither fits. SQL for metrics, vectors for recall, markdown for rationale — in that order.
  • Skills are for procedures. Conversation is for judgment. Don't skill-ify Q&A.
  • Active injury flag overrides everything. If athlete/injury-log.md has an entry in Active, it constrains the week before any other consideration.

Built by Sean Koval with Claude Code.

Ver o original no GitHub

Bom para

Relacionados