Application macOS¶

En vidéo · Étape 18 · 1 min 39

Sans terminal — L'application macOS : un questionnaire à la place des lignes de commande, le chat intégré ou votre assistant habituel, des données qui restent chez vous, une synchronisation qui n'écrit jamais chez Garmin, et la pesée du matin lue en lecture seule.

Regarder · English · Toutes les vidéos

L'application AI Running Coach évite le clonage Git, les options de ligne de commande et le lancement manuel du tableau de bord.

Installer¶

Téléchargez AI-Running-Coach-<version>-unsigned.dmg depuis la page des versions. Une seule image sert aux Mac Apple Silicon et Intel (macOS 13 ou plus récent).
Ouvrez le DMG et glissez AI Running Coach dans Applications.
Lancez l'application. Elle n'est pas signée par Apple : la première fois, macOS la bloque. Fermez l'alerte, ouvrez Réglages Système → Confidentialité et sécurité, puis cliquez sur Ouvrir quand même (une seule fois). En Terminal, xattr -dr com.apple.quarantine "/Applications/AI Running Coach.app" produit le même effet.
Renseignez votre prénom, votre année de naissance, votre expérience, vos disponibilités et votre lieu d'entraînement ; les blessures, données physiologiques et préférences personnelles sont proposées juste en dessous mais peuvent attendre.
Décrivez votre course et votre objectif. Si vous n'en avez pas encore, indiquez-le : la première conversation pourra servir à les définir.
Choisissez votre source sportive, votre pratique, vos sports croisés, le ton et la longueur des retours, les unités, votre équipe et la façon de parler au coach.
Cliquez sur Installer mon coach.

Sur un Mac neuf, macOS peut proposer une fois ses outils système gratuits (Git et Python). Acceptez leur installation, puis cliquez sur Réessayer dans AI Running Coach ; aucun réglage technique n'est demandé.

L'application place :

le moteur dans ~/Library/Application Support/AI Running Coach/engine ;
vos données, par défaut, dans ~/Documents/AI Running Coach ;
les jetons Garmin dans ~/.garminconnect, comme l'installation classique.

Vos séances, données de santé et plans ne sont donc jamais enfermés dans l'application. Une mise à jour ou une suppression de l'app ne supprime pas le dossier de données.

L'assistant remplit aussi planning/Runner_Profile.md et planning/active_objective.md avec les réponses fournies. Dans le volet facultatif, on peut saisir les performances, allures, VO2max, données physiologiques, blessures, motivations, sujets sensibles, sports croisés et plusieurs paires de chaussures avec leur date d'achat, kilométrage initial, usage et seuil d'usure. La première paire devient la paire par défaut si aucune ne l'était déjà.

L'application passe par le même moteur que /coach-setup : un champ déjà rempli n'est jamais remplacé silencieusement, une paire existante n'est pas dupliquée et les libellés officiels du profil ou de l'objectif ne sont jamais renommés.

Parler au coach¶

Deux modes sont proposés pendant l'installation :

Chat intégré : l'application installe le composant nécessaire et affiche ensuite Parler au coach. Il utilise OpenRouter, facturé à l'usage (environ 1 € par mois ; « 10 $ une fois ≈ un an de coaching »), avec un plafond quotidien. Gardez « Connecter OpenRouter » : pendant l'installation, une page OpenRouter s'ouvre, vous autorisez le coach et la clé est créée à votre place (scripts/arc_llm.py). « J'ai déjà une clé » reste disponible en repli. Si vous payez déjà ChatGPT Plus/Pro ou GitHub Copilot, choisissez « J'ai ChatGPT Plus/Pro » ou « J'ai GitHub Copilot » à côté d'OpenRouter : aucune clé ni facturation au jeton, et une fenêtre Terminal s'ouvre à la fin de l'installation pour vous connecter avec votre compte (adresse et code à valider dans le navigateur ; le bouton « Connecter ChatGPT » de l'écran final la rouvre si besoin). Forfaits : ChatGPT Plus ou Pro (l'offre Free est refusée), Copilot Pro, Pro+, Business ou Enterprise ; les limites de votre forfait s'appliquent et la synchronisation quotidienne les consomme aussi : la case « Synchroniser aussi avec mon forfait (une ou deux fois par jour) », cochée par défaut, la met sur l'abonnement (l'application n'a pas d'autre exécuteur de synchronisation dans ce mode ; décochée, la synchronisation automatique n'est pas installée). Voir Choisir son IA. Un lien mène aux réglages de confidentialité d'OpenRouter : pour des données de santé, n'autorisez que des fournisseurs qui ne conservent pas vos données. Voir Choisir son IA. La clé est conservée uniquement sur le Mac dans ~/.config/ai-running-coach/llm.env, en mode privé ; elle n'est jamais placée dans le dossier de données ni affichée dans les journaux.
Assistant IA habituel : choisissez Claude Code, GitHub Copilot, OpenCode, Gemini CLI ou Cursor Agent (Gemini CLI demande désormais une clé API Gemini ou une licence payante : un compte Google gratuit ne suffit plus, voir Choisir son IA). L'application installe automatiquement l'outil et prépare ses agents et sa connexion aux données, sans activer OpenRouter.

La synchronisation Garmin ou Intervals.icu en arrière-plan est toujours activée. Avec le chat intégré, elle réutilise OpenCode, la même clé OpenRouter et le plafond quotidien de synchronisation. Avec un assistant habituel, elle utilise le mode non interactif de l'assistant choisi — Claude Code, Copilot, OpenCode, Gemini ou Cursor — et donc le même compte, sans installer ni facturer un second fournisseur en secret. Une seule connexion initiale à cet assistant peut être demandée ; il n'a ensuite pas besoin de rester ouvert.

Quel que soit l'assistant, la synchronisation en arrière-plan n'écrit jamais côté Garmin, Intervals.icu, Strava ou COROS : les outils d'écriture de la source sont refusés un par un (Copilot : --deny-tool ; Gemini : excludeTools ; Cursor : règles Mcp(serveur:outil) de .cursor/cli.json, vérifiées avant chaque run). Avec Cursor, ces refus valent aussi en session interactive : pousser une séance vers la montre se fait alors avec un autre assistant. Le mode passerelle (--use-leanproxy) n'est pas pris en charge par ces assistants pour la synchronisation : utilisez le mode direct.

Dans ce second mode, il n'y a aucune commande à recopier. Après l'installation, Parler au coach avec… ouvre Terminal directement dans le dossier de données et lance l'assistant choisi. Au premier lancement seulement, celui-ci affiche sa propre connexion (compte Claude, GitHub, Google, etc.) ; les lancements suivants arrivent directement dans la conversation. Le Terminal reste visible parce qu'il constitue l'interface de ces assistants, mais l'utilisateur n'a ni cd ni commande d'installation à saisir.

Le chat intégré envoie les messages et le contexte utile au fournisseur du modèle. Le compte Garmin ou Intervals.icu reste une connexion distincte.

Connecter le compte sportif¶

Après l'installation, cliquez sur Connecter mon compte. Une fenêtre dédiée demande directement les informations Garmin Connect ou la clé Intervals.icu. Le mot de passe, la clé et le code MFA ne transitent pas par l'interface de l'application.

Revenez ensuite dans l'app : l'état de connexion est vérifié lorsqu'elle reprend le premier plan.

Emplacements des identifiants

L'application utilise toujours les emplacements par défaut : ~/.garminconnect pour Garmin et le dossier Intervals.icu par défaut. Les options --garmin-tokens et --intervals-dir, passées en ligne de commande à install.sh pour le workspace de l'application, ne sont pas prises en charge : l'application afficherait « non connecté » et se reconnecterait dans le dossier par défaut.

Une fois le compte connecté, le service de synchronisation installé par l'application récupère les nouvelles données aux heures configurées. Garmin et Intervals.icu utilisent la même source choisie pendant l'installation ; les données récupérées sont persistées dans le dossier de travail avant d'être affichées par le coach ou le tableau de bord.

Le bouton Synchroniser maintenant de l'écran principal lance exactement la même opération sans attendre la prochaine heure programmée. L'application affiche son avancement puis indique si les données sont à jour ou si une connexion demande votre attention.

Lancer le coach au quotidien¶

Ouvrez AI Running Coach depuis Applications, Spotlight ou le Dock, puis cliquez sur Parler au coach ou Tableau de bord. L'application démarre l'interface locale et ouvre le navigateur. Le serveur reste limité à 127.0.0.1 : il n'est pas exposé sur le réseau.

L'écran d'accueil permet aussi de :

retrouver le dossier de données dans le Finder ;
compléter plus tard le profil, l'objectif et les chaussures depuis le même questionnaire graphique ;
relancer le diagnostic d'installation ;
reconnecter le compte lorsque son accès expire ;
réessayer la mise à jour du moteur si une installation a été interrompue.

Mises à jour¶

L'application recherche automatiquement les nouvelles versions publiées. Le menu AI Running Coach → Rechercher une mise à jour… permet aussi une vérification immédiate. Dans les réglages, vous pouvez désactiver cette recherche ou activer le téléchargement et l'installation automatiques.

Après remplacement et relancement de l'app, son moteur est mis à jour automatiquement. Si une synchronisation est en cours, l'app attend sa fin et réessaie toutes les 30 secondes. En cas d'échec de configuration, les fichiers de l'ancien moteur sont restaurés et un bouton permet de réessayer. Vos données personnelles restent dans leur dossier séparé.

Les modifications de main arrivent à la prochaine version publiée ; elles ne sont pas installées individuellement. Une dernière installation manuelle du DMG est nécessaire pour passer d'une ancienne app sans ce mécanisme à la première version qui l'intègre. Les builds de développement sans configuration de signature Sparkle n'effectuent pas de recherche de mise à jour. Les releases embarquent une clé publique Sparkle et publient un flux de mises à jour, y compris pour les DMG -unsigned sans signature Apple Developer ID. Sparkle vérifie la signature Ed25519 des mises à jour. L'autorisation de macOS au premier lancement reste nécessaire pour une app sans signature Apple.

Pour les mainteneurs¶

Le DMG se construit sur macOS avec :

scripts/build-macos-dmg.sh

Voir macos/AI-Running-Coach/README.md pour la signature Developer ID et la notarisation Apple. Le projet n'a pas de compte Apple Developer : le workflow publie donc un DMG signé ad hoc, nommé …-unsigned.dmg, accompagné de son empreinte .sha256, et ajoute aux notes de la release la marche à suivre pour l'ouvrir. Si les secrets MACOS_CERTIFICATE_P12, MACOS_CERTIFICATE_PASSWORD, MACOS_SIGNING_IDENTITY, APPLE_ID, APPLE_TEAM_ID et APPLE_APP_PASSWORD sont un jour ajoutés, le même workflow signe, notarise et publie le DMG sous son nom normal.

Sur GitHub, les jobs macOS des tests et le workflow macOS (macos-dmg.yml) sont actifs par défaut : le dépôt est public, et les runners macOS standard y sont gratuits (limite : 5 jobs macOS simultanés). Pour les couper (fork privé, quota épuisé), poser la variable de dépôt ARC_MACOS_ON_GITHUB à false (gh variable set ARC_MACOS_ON_GITHUB --body false). Le DMG des tags v* reste construit sur CircleCI ; son offre open source ne couvre qu'environ 150 minutes macOS par mois, d'où des tests macOS restés sur GitHub.

Pour joindre le DMG à une release existante : onglet Actions → Application macOS → Run workflow, avec le tag dans le champ « tag ».

Le workflow Tag a release (Actions → Tag a release → Run workflow, depuis main) refuse de taguer si le job Tests n'a pas réussi sur la tête de main, puis pose le tag vX.Y.Z sur ce commit et crée la release officielle. Il ne pousse rien sur main (qui peut donc exiger une pull request et le statut Tests) : le DMG tire son numéro du tag (ARC_APP_VERSION), qui est aussi écrit dans le fichier VERSION du moteur embarqué. Le fichier VERSION du dépôt n'est qu'un repli pour une copie sans .git ; il se met à jour par une PR ordinaire, et le workflow signale un écart sans bloquer. Sur GitHub, le DMG n'est construit que si le champ « build_dmg » est coché au lancement (CircleCI le construit déjà pour chaque tag v*) ; il est alors signé si les secrets Apple existent, puis joint à la release. Un tag poussé manuellement crée la release (et l'image Docker), mais pas le DMG sur GitHub. Pour joindre un DMG plus tard, lancez Application macOS avec le tag ; le workflow attend alors que la release existe.