Mon coach de running est un dépôt Git et un agent Claude

Je finis ma séance. Ma montre se synchronise avec Strava toute seule, comme d'habitude. Je vais prendre ma douche.

Quand j'en sors, trois choses ont eu lieu sans que je touche à quoi que ce soit. L'analyse de la séance est écrite dans mon dépôt d'entraînement. Le plan de la semaine a été réajusté, avec la raison du changement notée à côté. Et sous l'activité Strava, il y a un commentaire de mon coach, qui me dit ce que la séance vaut et ce qu'elle change pour vendredi.

Ce coach n'est pas une application que j'ai développée. C'est un dépôt Git de fichiers Markdown, un abonnement Claude, et AgentsRoom pour tenir le tout. Aucun serveur écrit, aucune facture au token, environ un week-end de montage.

Le tout est publié en modèle : github.com/AgentsRoomDev/running-performance-coach. Vous pouvez le cloner et le rendre vôtre en remplaçant les emplacements laissés vides. Cet article explique comment il marche, morceau par morceau, en supposant que vous avez déjà entendu le mot « API » mais jamais écrit de webhook.

Pour situer : je cours depuis longtemps, 2h47 sur marathon, 1h13'59 sur semi, 33'45 sur 10 km. L'objectif du cycle en cours est de repasser sous les 34 minutes sur 10 km. C'est important pour la suite : un coach générique qui me réexplique ce qu'est une séance de seuil ne me sert à rien, et c'est exactement le problème que ce montage règle.

Ce qui se passe entre la fin de ma séance et le commentaire

La chaîne complète tient en six temps :

1. Ma montre envoie l'activité à Strava. Ça, c'est déjà le cas pour tout le monde.
2. Toutes les 15 minutes, un petit script Python demande à Strava s'il y a du neuf.
3. Quand il trouve une nouvelle séance, il en fabrique une fiche Markdown dans mon dépôt : les tours, les temps intermédiaires, le volume, la fréquence cardiaque. Que du mesuré.
4. Il réécrit aussi le titre et la description de l'activité sur Strava, pour que mon flux arrête d'afficher « Course de l'après-midi ».
5. Puis il envoie un message signé à AgentsRoom, qui ouvre un agent Claude avec la séance déjà en main.
6. Cet agent fait le travail de coach : il lit, il compare, il écrit l'analyse, il ajuste la semaine, il commite, il pousse, il commente sur Strava, il m'envoie le rapport long par mail.

Les cinq premiers temps sont de la plomberie. Le sixième est le sujet de cet article.

Le carnet d'entraînement est un dépôt Git, pas une base de données

C'est la décision qui change tout, et c'est aussi celle qui surprend le plus.

Une séance = un fichier, journal/2026/2026-09-03.md. Une semaine = un fichier, plan/weeks/2026-W36.md. Un changement de plan = un commit, avec sa raison dans le message. Il n'y a pas de base de données, pas de schéma, pas de migration, pas d'interface.

Trois conséquences, dans l'ordre d'importance :

Le coach peut relire sa propre histoire. Il sait ce qu'il a prescrit il y a trois semaines, et il peut vérifier si ça a marché. Un chatbot à qui vous racontez votre séance repart de zéro à chaque conversation. Un agent qui a un dépôt a une mémoire, et cette mémoire est lisible par un humain.

Je lis mon plan sur mon téléphone, dans l'application GitHub. Le README.md du dépôt n'est pas une page de présentation : c'est mon tableau de bord. Le contrat écrit dans CLAUDE.md est explicite là-dessus, aucune planification n'est terminée tant que le README ne la reflète pas. Résultat : je n'ai aucune interface à maintenir, et pourtant j'ai un écran qui me dit ce que je fais aujourd'hui.

Rien n'est irréversible. Tout ce que l'agent écrit est un commit. Je peux le lire, le contester, le revert. C'est très différent d'une application qui décide dans son coin.

Étape 1 : Strava réveille un petit script

Strava expose une API : un moyen, pour un programme, de demander « donne-moi les activités récentes de cet athlète ». Le script strava_sync.py fait exactement ça, et transforme la réponse en fiche de séance.

La partie intéressante n'est pas l'appel réseau, c'est la reconstruction. Une montre enregistre des tours bruts. Le script, lui, doit deviner quelle séance c'était :

Tour 1  : 4,40 km en 26'07 (5:56/km)   ← échauffement
Tour 2  : 1,00 km en 3'41  (3:41/km)   ← répétition 1
Tour 3  : 0,20 km en 1'59  (9:55/km)   ← récupération
...                                      → « 5 x 1000m r' 2' »

Il essaie toutes les découpes de la forme « les k tours les plus rapides sont les répétitions » et garde la meilleure qui tient debout. Ça a l'air trivial et ça ne l'est pas : un regroupement naïf par vitesse se fait piéger dès qu'un échauffement est plus rapide qu'une récupération.

Surtout, la forme de la séance est reconstruite depuis la montre, jamais depuis le plan. C'est tentant de faire l'inverse (le plan dit 5 x 1000m, autant l'écrire) et c'est exactement l'erreur : tout l'intérêt est de détecter les jours où j'ai fait autre chose. Quand les deux divergent, c'est cette divergence qui est l'information, et le coach la voit :

Prévu 3 x 8' → couru en continu

Deux avertissements avant que vous ne vous lanciez.

L'API Strava exige un abonnement développeur payant depuis juin 2026. Sans lui, chaque appel répond 403 Application Status Inactive. Le repli existe et il est prévu dans le modèle : exporter un fichier TCX depuis votre montre et le passer à import_tcx.py. Tout ce qui est en aval de l'import fonctionne à l'identique.

Les quotas sont larges, mais réels. Sur mon application, 300 requêtes toutes les 15 minutes et 3 000 par jour en lecture. Le script en consomme une par passage en régime stable, soit 96 par jour. On est loin du plafond, mais c'est le genre de chose qu'on vérifie avant, pas après.

Étape 2 : le script réveille l'agent, avec une signature

C'est ici que ça devient intéressant.

Un webhook, c'est l'inverse d'une question. Plutôt que de demander toutes les cinq minutes « est-ce qu'il y a du nouveau ? », vous donnez une adresse web à un programme, et c'est lui qui vous envoie un message quand l'évènement arrive. Vous ne payez rien tant qu'il ne se passe rien.

AgentsRoom expose exactement ça : un déclencheur webhook. Vous créez un déclencheur dans l'application, elle vous rend une URL et un secret. Quiconque envoie un message JSON sur cette URL ouvre un agent, avec le prompt que vous avez écrit et le contenu du message déjà injecté dedans.

Le message que mon script envoie est volontairement minuscule :

{
  "type": "created",
  "title": "03/09 · 5 x 1000m r' 2'",
  "body": "Séance du 03/09/2026 importée depuis Strava.\n\nSéance qualité : 5 x 1000m r' 2'\nSplits : 3'41 - 3'40 - 3'38 - 3'40 - 3'35\n\nVolume total : 12,51 km en 1h07'42 (5:25/km), D+ 56 m\nSéance prévue : RP10-5x1000\n\nFiche de séance : journal/2026/2026-09-03.md\nFiche de semaine : plan/weeks/2026-W36.md"
}

Notez ce qui n'y est pas : le texte du plan. Le webhook transporte le code de la séance prévue et le chemin des fiches, jamais leur contenu. Un agent qui a le dépôt ira les lire lui-même ; un agent qui ne l'a pas n'a rien à faire de mes consignes internes. C'est la même règle que pour les descriptions publiées sur Strava.

La signature, et le piège qui va avec

Une URL publique qui ouvre un agent, ça ne peut pas rester ouvert au premier venu. Le déclencheur est donc signé : le script calcule une empreinte du message avec le secret partagé (un HMAC-SHA256, si le terme vous parle) et l'envoie dans l'en-tête X-AgentsRoom-Signature. Le serveur recalcule la même empreinte de son côté ; si elle ne correspond pas, il refuse.

Sans signature, la réponse est nette :

{"error":"REJECTED","message":"Signature missing."}

Et voici le piège, qui m'a coûté une soirée. La signature couvre les octets exacts qui partent sur le réseau, pas l'objet en mémoire. Si vous signez un fichier tel qu'il est sur le disque, puis que vous laissez une autre couche re-sérialiser l'objet (un espace en plus, un ordre de clés différent, un accent échappé autrement), vous obtenez une signature parfaitement valide pour un message que le serveur ne recevra jamais. Le rejet est indébuggable : tout a l'air correct des deux côtés.

Le correctif tient en une phrase : on sérialise et on signe au même endroit. Dans le modèle, c'est la fonction post_json qui fait les deux, et rien d'autre n'a le droit de toucher au corps du message.

Étape 3 : trois couches disent au coach qui il est, comment ça marche ici, et quoi faire maintenant

Un agent qui coache, ce n'est pas un gros prompt. C'est trois textes séparés, et la séparation compte.

Couche 1, la persona : qui il est

Un prompt système attaché à l'agent dans AgentsRoom. Il porte la philosophie d'entraînement, et il est délibérément générique au sport : il coacherait n'importe qui.

Votre travail n'est pas simplement de générer des plans d'entraînement. Vous coachez l'athlète en continu, en analysant son entraînement, en comprenant sa forme actuelle, en adaptant les séances à venir. […] Parlez comme un entraîneur expérimenté, pas comme un chatbot de motivation.

Il dit aussi ce qu'il ne fait pas : ne pas juger une séance uniquement sur « l'allure prévue a-t-elle été tenue », être explicite sur l'incertitude d'une prédiction de chrono, et ne pas valider un objectif simplement parce que l'athlète en a envie. Cette dernière ligne est celle qui rend le coach utile.

Vous n'avez pas à la réécrire : cette persona est publiée dans le catalogue d'agents d'AgentsRoom sous le nom Entraîneur de Performance en Course. Un clic l'installe chez vous, prête à l'emploi.

Couche 2, CLAUDE.md : comment ça marche ici

C'est le contrat, lu au début de chaque session. Il contient l'arborescence des fichiers, les règles qui la tiennent, les principes d'entraînement qui contraignent toute proposition, et surtout le rituel : la séquence exacte à dérouler quand une séance est rapportée.

Un extrait, parce qu'il montre le niveau de précision :

Ordre de sacrifice quand la semaine déraille : d'abord les minutes en plus sur les footings, puis le renforcement, puis la longueur de la sortie longue, puis une séance qualité. Jamais la semaine entière.

C'est là que le coach arrête d'être un chatbot. Il n'improvise pas un mode opératoire à chaque fois, il suit celui que j'ai écrit une bonne fois. Si vous ne devez lire qu'un fichier du dépôt modèle, lisez celui-là.

Couche 3, le prompt du déclencheur : quoi faire maintenant

C'est le message remis à l'agent quand une séance atterrit. Il reçoit l'activité par des variables de gabarit : {{event.title}}, {{event.body}}, {{event.url}}. L'agent démarre donc avec la séance déjà en main, au lieu d'aller la chercher.

Voici son ossature, telle qu'elle est dans le déclencheur :

Nouvelle séance importée depuis Strava.

**{{event.title}}** · activité {{event.id}}
{{event.url}}

{{event.body}}

---

Tu es dans le dépôt `training-plan`. Lis `CLAUDE.md` en premier : il fait loi.
Tu écris en français et tu me tutoies partout (§3).

Le rituel du §6 s'applique, mais son **étape 1 est déjà faite** :
`strava_publish.py` a créé la fiche de journal et l'a commitée. Tu reprends à
l'étape 2 et tu vas jusqu'au bout. Trois livrables, dans cet ordre :
**l'analyse dans le dépôt**, **le commentaire sous l'activité Strava**, **le mail**.

⚠️ **Tu tournes en automatique : personne ne lira une question.** Ne demande
jamais d'arbitrage : tu décides, tu agis, et tu dis dans ton compte rendu ce
que tu as tranché et pourquoi.

## 1 · Analyser et ajuster le plan (rituel §6, étapes 2 à 6)

1. `git pull --rebase` avant toute chose : la fiche peut venir du serveur.
2. Lis, dans cet ordre : la fiche du jour, la fiche de semaine,
   `athlete/zones-and-paces.md`, et **les 3 dernières fiches de séance** :
   une séance ne se juge jamais seule.
3. Écris la section `## Analyse` : **le verdict d'abord**, puis les signaux
   qui le portent, puis ce que ça change.
   ⛔ Si `## Analyse` est déjà remplie, ne la réécris pas.
4. Mets à jour la fiche de semaine et trace **tout** changement de plan
   sous `## Ajustements`, avec sa raison.
5. **Régénère le `README.md`** : c'est l'écran que je lis sur mon téléphone.
6. Commit et push, chemins explicites, ⛔ jamais `git add -A`.

## 2 · Kudos et commentaire sur Strava
   ⛔ Un commentaire Strava est PUBLIC : pas de fréquence cardiaque cible,
   pas de bobo, pas d'arbitrage interne, pas de chrono prédit.

## 3 · Le rapport complet par mail

La ligne qui fait le plus de travail est celle du milieu : « personne ne lira une question ». Un agent qui tourne sans personne devant l'écran et qui demande un arbitrage ne fait pas d'erreur, il s'arrête simplement, et vous le découvrez le lendemain.

Quel modèle, et pourquoi un million de tokens n'est pas un caprice

Le contexte long n'est pas de la coquetterie. Pour juger une séance correctement, le coach lit la fiche du jour, la fiche de la semaine, la table des allures de référence, et les trois séances précédentes. Une séance ne se juge jamais seule : la charge accumulée, l'enchaînement des jours et les points de vigilance en cours changent complètement le verdict. Trois répétitions à 3'38 après une sortie longue de deux heures la veille ne racontent pas la même histoire que les mêmes 3'38 après un jour de repos.

Le mode autonome n'est pas de la négligence, c'est une conséquence : une exécution sans personne devant l'écran n'a personne pour approuver un git push. Et l'accès navigateur est ce qui permet à l'agent d'aller commenter sur Strava et d'envoyer le mail, deux choses qui n'ont pas d'API pratique ici.

Ce qui est automatisé, et ce qui ne l'est délibérément pas

C'est la décision de conception dont je suis le plus content, et elle est facile à rater.

Le travail d'import enregistre et publie, il ne juge jamais.

Un script qui se mettrait à juger produirait des verdicts sans contexte, avec une logique figée dans du code que personne ne relit. Le jugement demande de tenir ensemble la charge de la semaine, la forme du moment, ce qui a été dit la dernière fois : c'est du travail de coach, et c'est l'agent qui le fait, avec tout le dossier sous les yeux.

Le bénéfice pratique est immédiat : quand l'agent n'a pas tourné (machine éteinte, API en carafe), la fiche existe quand même. Rien n'est perdu, seul le commentaire manque, et il suffit de rejouer.

Autre choix qui va dans le même sens : le script ne tient pas de fichier d'état pour savoir ce qu'il a déjà traité. C'est la description sur Strava qui fait foi. Vide, il écrit ; portant sa signature, il passe ; non vide et sans signature, c'est vous qui l'avez écrite et il n'y touche pas. Un fichier d'état local n'aurait rien pu dire de ce qu'une autre machine a fait ; là, deux machines peuvent tourner en parallèle sans se marcher dessus.

Deux autres règles de séparation, gravées dans le dépôt et qu'il ne faut pas contourner :

• la description publiée sur Strava ne recopie jamais le texte du plan : ma fiche de semaine contient des fréquences cardiaques cibles et des arbitrages qui n'ont rien à faire sur une activité publique ;
• une description écrite à la main n'est jamais écrasée.

Le commentaire qui atterrit sous l'activité

L'intérêt n'est pas l'auto-félicitation. C'est que le verdict du coach soit lisible depuis mon téléphone, sous l'activité, sans ouvrir le dépôt, et qu'il reste là, attaché à la séance, pour toujours.

Le commentaire est donc volontairement étroit : un emoji de verdict, le chiffre qui le porte, et ce que ça change pour la prochaine séance. Environ 250 caractères.

✅ Cinq répétitions à 3'39 de moyenne pour une cible à 3'38-3'44, et le cardiaque plat sur tout le bloc. La table d'allures tient. Vendredi reste en footing : tu as dépensé la marge de la semaine.

La version longue, celle avec les fréquences cardiaques, le point de vigilance que j'ai signalé et l'arbitrage sur le volume de la semaine prochaine, part dans le dépôt et dans le mail. Deux canaux, deux publics, et c'est le prompt qui tient la frontière.

Trois trucs qui ne cassent qu'en production

Chacune de ces lignes existe parce que quelque chose a cassé sans elle. Elles sont plus instructives que le reste de l'article.

1. Épingler le navigateur. J'ai deux extensions Claude connectées dans Chrome. Rien ne garantit laquelle l'agent obtient, et une seule porte la session Strava. Résultat : une exécution sur deux, l'agent se retrouvait dans le mauvais navigateur, non connecté, et ne pouvait rien commenter. Le choix du navigateur par identifiant d'appareil n'est pas conservé d'une session à l'autre : il doit donc être dans le prompt, avec l'interdiction explicite d'aller demander à l'utilisateur lequel choisir. En automatique, une question est un blocage.

2. Le champ de commentaire Strava n'a pas de maxlength. Rien, dans le navigateur, n'empêche d'écrire trop long : c'est le serveur qui refuse à l'envoi. Un agent qui rédige un beau paragraphe de 600 caractères le tape entièrement, clique sur « Poster », et se prend un échec qu'il ne comprend pas. Le prompt doit donc imposer la brièveté avant la rédaction, et prévoir le cas : si l'envoi échoue, on raccourcit et on republie, jamais on ne coupe en deux commentaires.

3. Un commentaire de coach par activité. Quand on rejoue un évènement pour tester (ce qu'on fait beaucoup au début), sans cette règle l'agent empile les commentaires sur une activité déjà traitée. Le prompt lui fait donc lire l'onglet « Commentaires » avant d'écrire, et passer son tour s'il s'y trouve déjà. Même logique côté dépôt : si la section ## Analyse est déjà remplie, on ne la réécrit pas.

Ce que ça coûte

Il n'y a pas de clé API facturée au token dans ce montage. C'est le point que je trouve le plus sous-estimé : la même chose bâtie sur une API payée à l'usage aurait un compteur qui tourne à chaque séance, et je ne l'aurais probablement pas gardée.

Le construire ce week-end

Les étapes, dans l'ordre. Comptez une soirée si vous avez déjà un compte Strava et un abonnement Claude.

1. Cloner le modèle et le rendre vôtre.

git clone https://github.com/AgentsRoomDev/running-performance-coach.git mon-coach
cd mon-coach
rm -rf .git && git init

Rendez votre copie privée. Un carnet d'entraînement contient des données de santé : fréquence cardiaque, sommeil, blessures. Le modèle est public, votre copie ne doit pas l'être.

Remplissez ensuite, dans cet ordre : athlete/profile.md (qui vous êtes comme coureur), athlete/records.md (vos records), athlete/constraints.md (les créneaux dont vous disposez vraiment), athlete/zones-and-paces.md (vos allures de référence), plan/objective.md (la course et l'objectif), puis CLAUDE.md, où vous remplacez chaque emplacement {{...}}.

Ouvrez enfin le dépôt avec votre agent Claude et dites-lui : « lis CLAUDE.md et athlete/, puis construis-moi la première semaine. »

2. Brancher Strava.

cp .env.example .env && chmod 600 .env
python3 scripts/strava_oauth.py     # un clic dans le navigateur, une seule fois
python3 scripts/strava_sync.py --dry-run

Le --dry-run affiche ce qui serait écrit sans rien écrire. C'est le moment de vérifier que la reconstruction des séances vous convient.

3. Créer le déclencheur dans AgentsRoom. Dans Triggers, New trigger :

AgentsRoom fabrique une URL et un secret de signature. Mettez les deux dans votre .env :

WEBHOOK_URL=https://agentsroom.dev/api/triggers/t_xxxxxxxxxxxx
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx

4. Le tester avant de lui faire confiance.

python3 scripts/webhook_replay.py scripts/examples/webhook-session.json --dry-run
python3 scripts/webhook_replay.py scripts/examples/webhook-session.json

Ça rejoue une séance dans le déclencheur sans attendre votre prochaine sortie et sans toucher à l'état du travail automatique. Vous devez voir ✅ HTTP 202, et un onglet d'agent doit s'ouvrir dans AgentsRoom.

5. Le faire tourner toutes les 15 minutes.

bash scripts/systemd/install.sh          # sur un serveur Linux

Une unité oneshot plus un minuteur : pas de processus résident, et un passage manqué pendant que la machine était éteinte est rattrapé au démarrage suivant.

Si vous n'avez pas de machine allumée en permanence, sautez cette étape : lancez strava_sync.py à la main quand ça vous chante, ou racontez simplement votre séance à l'agent dans une conversation. Le rituel de CLAUDE.md fonctionne à l'identique. Vous perdez l'automatisation, pas le coach.

Ce que j'en retiens, au-delà de la course à pied

Ce montage n'a rien de spécifique au running. Ce qu'il montre, c'est un motif reproductible pour à peu près n'importe quel domaine où vous accumulez des données personnelles et où vous aimeriez un avis compétent dessus.

Trois briques, et c'est tout. Un dépôt Git de fichiers Markdown comme mémoire lisible par la machine et par vous. Un évènement qui réveille un agent au lieu d'un agent qui interroge en boucle et coûte des tokens pour rien. Trois couches de configuration qui séparent proprement qui est l'agent, comment il travaille chez vous, et ce qu'il doit faire à l'instant.

Remplacez « séance de course » par « relevé bancaire », « session de code », « mesure de glycémie » ou « note de lecture » : la mécanique ne change pas.

Questions fréquentes

Faut-il savoir coder pour se construire un coach running en IA ?

Il faut savoir lancer une commande dans un terminal et éditer un fichier texte. Le dépôt modèle est prêt à cloner, les scripts Python n'utilisent que la bibliothèque standard (aucun pip install), et la partie coaching se configure en écrivant du français dans des fichiers Markdown. Le vrai travail n'est pas technique : c'est de décrire honnêtement qui vous êtes comme coureur et ce que vous visez.

Combien ça coûte par mois ?

L'agent tourne sous l'abonnement Claude que vous avez déjà (Pro ou Max) : il n'y a pas de clé API facturée au token. Il reste éventuellement une petite machine allumée en permanence pour interroger Strava toutes les 15 minutes, autour de 5 euros par mois sur un VPS, ou zéro sur un Raspberry Pi. Le dépôt Git privé est gratuit. Reste l'API Strava, qui exige un abonnement développeur depuis juin 2026.

Pourquoi un dépôt Git plutôt qu'une base de données ?

Parce que l'historique devient lisible par le coach et par vous. Chaque séance est un fichier Markdown, chaque changement de plan est un commit avec sa raison. L'agent peut relire ce qu'il a prescrit il y a trois semaines et vérifier si ça a marché, et vous lisez votre plan sur votre téléphone dans l'application GitHub, sans écrire une ligne d'interface.

Qu'est-ce qu'un webhook, expliqué simplement ?

Un webhook, c'est un service qui vous appelle au lieu que vous l'appeliez. Plutôt que de demander toutes les cinq minutes « est-ce qu'il y a du nouveau ? », vous donnez une adresse web à un programme, et c'est lui qui vous envoie un message quand l'évènement arrive. Ici, le script qui importe la séance envoie ce message à AgentsRoom, qui ouvre un agent Claude dans la seconde. C'est aussi ce qui rend le montage économe : un agent qui interroge en boucle consomme des tokens à chaque tour, un déclencheur webhook ne coûte rien tant qu'il ne se passe rien.

Est-ce que ça marche pour un autre sport que la course à pied ?

Oui. L'import reconstruit des tours de montre, et le vélo comme la natation en enregistrent aussi. Ce qui change, ce sont les fichiers de stratégie et le catalogue de séances, qui sont du texte que vous réécrivez. La mécanique (import, webhook, agent, dépôt) ne bouge pas.

Est-ce que l'agent peut se tromper et casser mon plan ?

Il peut se tromper, mais il ne peut pas casser grand-chose : tout ce qu'il écrit est un commit Git que vous pouvez lire, discuter et annuler. Le fichier CLAUDE.md lui interdit explicitement de réécrire l'historique, d'inventer des données que vous n'avez pas fournies, de changer le plan sans tracer la raison, et de donner un avis médical. Une douleur suspecte, il vous renvoie vers un professionnel.

---

Le dépôt modèle est ici : AgentsRoomDev/running-performance-coach. Clonez-le, remplissez vos allures, et vous avez votre coach. Si vous voulez voir la brique qui réveille l'agent, elle est décrite sur la page déclencheurs webhook, et AgentsRoom se télécharge ici.