Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

33.7 KB
Raw Blame

Notch Buddy — intégrations

Règle d'or : vérifier la doc officielle au moment d'implémenter. Les formats ci-dessous sont le plan, pas une garantie. Sources à relire :


1. Claude Code (sessions de Louis)

Architecture

claude (terminal, VS Code, app Claude)
  └─ hook "command" ─► nb-hook (petit exécutable Swift, livré avec l'app)
                         └─ socket Unix ─► Notch Buddy.app
                         ◄─ décision (pour PermissionRequest)
  • nb-hook (script shell) et nb-hook.py (relais Python) : écrits par l'app (HookServer.swift). Version GitHub : au lancement, dans ~/Library/Application Support/NotchBuddy/. Version App Store : à l'installation des hooks, dans ~/.claude/coucou/. Voir docs/AGENTS.md pour les autres agents qui utilisent ces scripts.
  • Socket : ~/Library/Application Support/NotchBuddy/nb.sock (version GitHub) ou ~/Library/Containers/fr.louisraille.Coucou/Data/nb.sock (version App Store). Dossier en 0700, socket en 0600. Connexions du même utilisateur seulement (vérification getpeereid). 1 Mio et 5 s maximum par message, 32 connexions simultanées.
  • nb-hook [--agent <nom>] <Event> lit le JSON du hook sur stdin, ajoute le contexte du terminal (TERM_PROGRAM, ITERM_SESSION_ID, TERM_SESSION_ID, __CFBundleIdentifier, le tty trouvé en remontant les processus parents, cwd) et, si --agent est fourni, le champ coucou_agent, puis l'envoie à l'app.
  • Si l'app ne répond pas en 300 ms, nb-hook sort en code 0 sans rien écrire : Claude Code continue normalement. Jamais de blocage.
  • Champ optionnel coucou_agent : nom en minuscules, chiffres et tirets, 24 caractères au plus. Si absent ou invalide, l'événement va dans la pastille Claude. Voir docs/AGENTS.md pour les autres agents.

Événements à brancher et état du bonhomme

Hook Effet dans l'app
SessionStart crée la tâche (nom = dossier), état idle
UserPromptSubmit état thinking, ligne du défilé = début du prompt
PreToolUse état working, ligne = outil + cible (« Edit Invoice.swift », « Bash npm test »)
PostToolUse / PostToolUseFailure met à jour la ligne ; un échec reste working
PermissionRequest alerte approval (voir plus bas)
Notification selon le type : attente d'entrée → question si une question est posée, sinon rien ; limite d'usage → ratelimit
Stop état finished → vue finished 5,2 s, résumé = dernière phrase utile de la réponse si disponible
StopFailure (si présent dans la doc) alerte error
SubagentStart / SubagentStop afficher « + sous-agent » dans le défilé
SessionEnd retire la tâche

Vérifier dans la doc la liste exacte des événements et leurs champs.

Approuver depuis le notch

  • Sur PermissionRequest, nb-hook attend la décision de l'app (défaut 110 s, réglable) puis écrit sur stdout le JSON de décision du hook (d'après la doc actuelle : hookSpecificOutput avec decision.behavior = allow ou deny). Timeout du hook dans settings.json : décision + 10 s.
  • Pas de réponse avant le délai, ou app fermée → aucune sortie, le terminal affiche sa demande habituelle. Si Louis répond dans le terminal, l'app retire l'alerte au prochain événement de la session.
  • Un bug a été signalé où deny était ignoré sur PermissionRequest (issue GitHub anthropics/claude-code #19298). Tester allow et deny ; si deny ne marche pas, basculer la décision sur PreToolUse (permissionDecision) pour les outils concernés.
  • « Toujours autoriser » : si la doc permet de renvoyer une règle de permission persistante, l'utiliser. Sinon l'app garde sa propre liste (projet + outil + motif de commande) et répond allow automatiquement ensuite. Liste visible et supprimable dans les réglages.
  • Raccourcis Y / N quand la vue approval est ouverte.

Répondre aux questions (AskUserQuestion)

  • Claude Code 2.1.85+ : AskUserQuestion arrive en PreToolUse (avec matcher: "AskUserQuestion"), non plus en PermissionRequest. Un hook dédié avec --ask et un timeout de 130 s est requis dans settings.json. Si ce hook manque, l'app affiche la bannière « Hooks outdated — update them to answer Claude's questions from the notch » dans les réglages et propose la mise à jour.
  • PermissionRequest pour AskUserQuestion : l'app répond {"permissionDecision":"ask"} immédiatement (no-op) et n'affiche pas de carte.
  • PreToolUse général pour AskUserQuestion : l'app ignore l'événement (pas de mise à jour de l'état .working).
  • tool_input.questions : tableau de 1 à 4 questions, chacune avec question (texte), header (≤ 12 car.), options (2 à 4, chacune label + description), multiSelect.
  • L'app parse en un modèle Foundation (AskQuestion) ; si le parse échoue, nb-hook.py n'émet rien → Claude Code re-pose la question dans le terminal.
  • La vue question affiche une question à la fois (compteur 1/N), les options en grille fluide (ChipFlowLayout), un champ libre « Other… », et un lien « Reply in terminal » dans l'en-tête (envoie ask, aucune sortie).
  • Single-select : clic = réponse immédiate (pas de bouton Send). Multi-select : toggles + bouton Send/Next, désactivé tant qu'aucun choix.
  • Réponse via socket : {"decision":"answer","answers":{"<question>":"<label>"}}. Multi-select : valeur [String] (tableau, Claude Code 2.1.136+). Single-select et « Other… » : valeur String.
  • nb-hook.py --ask : si decision == 'answer' → émet hookSpecificOutput avec hookEventName: "PreToolUse", permissionDecision: "allow" et updatedInput: {questions, answers} — Claude Code reçoit les réponses et continue.
  • Fallback : si l'app ne répond pas (absente, timeout 125 s) ou renvoie ask, nb-hook n'émet rien → Claude Code re-pose la question dans le terminal.

Sauter au terminal

Contexte capté Action
TERM_PROGRAM=Apple_Terminal + tty AppleScript Terminal : sélectionner l'onglet dont le tty correspond, activer
TERM_PROGRAM=iTerm.app + ITERM_SESSION_ID AppleScript iTerm : sélectionner la session, activer
TERM_PROGRAM=vscode ouvrir le dossier cwd dans VS Code ou Cursor (selon __CFBundleIdentifier)
Ghostty, Warp, autre activer l'app
Conductor (__CFBundleIdentifier=com.conductor.app, sans TERM_PROGRAM) activer Conductor (pas de lien documenté vers un workspace précis)
rien (app Claude) activer l'app Claude
Demande l'autorisation Automatisation la première fois (normal).

Installation des hooks : procédure obligatoire

  1. Lire ~/.claude/settings.json (le créer s'il n'existe pas).
  2. Copier en ~/.claude/settings.json.bak-AAAAMMJJ-HHMM.
  3. Fusionner : ajouter les hooks Notch Buddy sans toucher aux hooks existants. Chemin de nb-hook entre guillemets (il contient un espace).
  4. Montrer le diff à Louis, attendre son OK, écrire.
  5. Bouton « Désinstaller les hooks » dans les réglages qui retire uniquement les entrées Notch Buddy.

1bis. Jauge de forfait Claude (statusLine)

Affichage : petit pill dans l'en-tête de l'île (vue home uniquement) — plus de pastille dans le catalogue Active pills.
Plateforme : macOS uniquement (build GitHub)
Plans : Pro et Max uniquement (le champ rate_limits n'est présent que pour ces plans)

Affiche la consommation du forfait Claude via un pill coloré dans l'en-tête de l'île. Couleur dynamique : vert #22C55E < 50 %, orange #F59E0B 50–80 %, rouge #F4505E ≥ 80 %, gris #6B7079 sans données. Cliquer sur le pill bascule showingPlanDetail, ce qui remplace la carte en cours par ClaudePlanCardView. showingPlanDetail se remet à false au changement de focusId, de vue ou de mode.

Données

Claude Code envoie, à chaque réponse et avec un debounce de 300 ms, un JSON à la commande statusLine configurée dans ~/.claude/settings.json. Ce JSON contient :

{
  "session_id": "…",
  "rate_limits": {
    "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
    "seven_day":  { "used_percentage": 67.0, "resets_at": 1738598400 }
  }
}

used_percentage va de 0 à 100. resets_at est un epoch UNIX en secondes. Le champ rate_limits peut être absent (plan Free, ou première réponse de la session). Chaque fenêtre peut être absente indépendamment. Les valeurs absurdes (< 0 ou > 100) sont ignorées. Une fenêtre dont resets_at est passé s'affiche à 0 % jusqu'à la prochaine mise à jour.

Relais

nb-hook.py, en mode --statusline, lit le JSON de stdin, en extrait rate_limits et session_id, et envoie {"coucou_kind": "statusline", …} au socket en fire-and-forget (timeout 0,3 s). Si une statusLine précédente existait (sauvegardée dans statusline-previous.json à côté de nb-hook), elle est appelée via /bin/sh -c avec le même stdin et sa sortie est réécrite telle quelle (timeout 10 s, couleurs ANSI comprises).

Installation et activation

Réglages → Agents → Plan usage → Install relay. Coucou montre le diff de ~/.claude/settings.json avant d'écrire quoi que ce soit. Si une statusLine existait, seul le champ command est remplacé ; les autres champs (padding, refreshInterval, etc.) sont conservés. Une fois le relais installé, activer le toggle Show in the notch pour faire apparaître le pill dans l'en-tête. Si le toggle est activé avant l'installation du relais, l'installation est lancée automatiquement ; le toggle s'active après confirmation.

Désinstallation

Réglages → Agents → Plan usage → Uninstall relay. Remet l'objet statusLine d'origine à l'identique, ou retire la clé si elle n'existait pas. Si la statusLine actuelle n'est plus celle de Coucou (l'utilisateur l'a changée), elle n'est pas touchée.


1ter. Diff en direct (live diff)

Sur PostToolUse pour Edit, MultiEdit et Write (Claude Code, Cursor), l'app calcule un diff ligne à ligne et l'affiche dans le fil de l'île.

Données

  • Edit : old_string → new_string
  • MultiEdit : liste edits, chaque entrée old_string → new_string
  • Write : content — tout le contenu est compté en ajout (on ne lit jamais le fichier sur le disque)
  • Le diff est calculé localement (Foundation, jamais de lecture sur le disque).
  • Limite : 200 Ko de texte combiné ou 4 000 lignes combinées → bilan seul, "Diff too large".
  • Mémoire : 50 diffs max par session, les plus anciens sont oubliés ; tout effacé à la fin de la session (SessionEnd) ou après une heure sans activité.

Fil (TickerView) — les étapes de modification affichent le nom du fichier, +N en vert #22C55E et −M en rouge #F4505E, petits et monospacés.

Carte diff — un clic sur une étape de modification ouvre la carte diff dans la vue principale :

  • En-tête : nom du fichier + bilan + bouton ↗ (ouvre dans VS Code via code -g fichier:ligne, sinon NSWorkspace)
  • Lignes en monospace 10,5 pt, fond vert ou rouge à 12 %, symbole +/− en marge, 3 lignes de contexte
  • Défilement vertical ; Échap ou clic sur l'en-tête pour revenir au fil

Vue Terminé (FinishedView) — affiche la dernière ligne utile de la session (finalLine → dernière étape non-diff → "Session finished"), sur une ligne (.lineLimit(1).truncationMode(.tail)). Pas de liste de fichiers.


1quater. GitHub (pulse)

Plateforme : macOS uniquement (build GitHub)

Token : token classique avec scope repo, ou token fin avec accès en lecture à Pull requests, Commit statuses et Actions. Stocké dans le Trousseau (github-token).

Données récupérées

Deux requêtes GraphQL séparées (POST https://api.github.com/graphql, même token, même en-tête) :

Requête pulse :

  • Mes PRs ouvertes (20 dernières par date de mise à jour) : numéro, titre, URL, isDraft, reviewDecision, oid du dernier commit, état CI du dernier commit (statusCheckRollup.state)
  • PRs à reviewer (recherche is:pr is:open review-requested:@me, 20 max) : numéro, titre, URL, auteur
  • CI branche par défaut (10 derniers dépôts propres, non archivés) : oid et état CI du commit HEAD sur defaultBranchRef

Cadence pulse : 5 min (pas de PRs en attente) ou 60 s (au moins une PR/CI en état PENDING ou EXPECTED). Première requête 10 s après le lancement.

Rafraîchissement pulse à l'ouverture : GithubPoller.refreshIfStale(maxAge: 60) appelé quand integration_github prend le focus, quand l'île s'étend avec GitHub en focus, et à l'ouverture d'une vue détail (sauf Activity). Si données < 60 s ou requête en vol, ignoré.

Requête activité (contributionCalendar) :

query { viewer { login contributionsCollection { contributionCalendar {
  totalContributions weeks { contributionDays { date contributionCount contributionLevel weekday } }
} } } }
  • contributionLevel : NONE → 0, FIRST_QUARTILE → 1, SECOND_QUARTILE → 2, THIRD_QUARTILE → 3, FOURTH_QUARTILE → 4. Valeur inconnue → 0.

Cadence activité : 30 min, première requête 15 s après le lancement.

Rafraîchissement activité à l'ouverture : GithubPoller.refreshActivityIfStale(maxAge: 300) appelé à l'ouverture de la vue Activity. Si données < 5 min ou requête en vol, ignoré.

Données gardées en mémoire (AppState.githubActivity). Remises à nil si token change ou si integration_github est désactivé.

États CI (CIState)

Valeur GitHub CIState
PENDING, EXPECTED .pending
SUCCESS .success
FAILURE, ERROR .failure
null ou autre .unknown

Alertes

Premier poll après lancement : toujours silencieux. Polls suivants :

Même headSha (oid) qu'au poll précédent — règles classiques de transition :

  • CI passe de !failure → failure : .ciFailed / .mainFailed
  • CI passe de pending → success : .ciPassed

headSha différent ou PR/dépôt absent au poll précédent (nouveau commit ou nouvelle PR, CI déjà terminée avant le poll) :

  • CI = success → .ciPassed (PR uniquement ; pas d'alerte vert pour main)
  • CI = failure → .ciFailed / .mainFailed
  • CI = pending → rien (le poll suivant, même sha, verra la transition)
Événement Badge Son
CI PR failure / main .error (rouge) error
Nouvelle review demandée .finished (vert) question
CI PR success .finished (vert) finish

Priorité : failure > review demandée > success. Un seul badge/son par cycle.


2. n8n (workflows de Louis)

  • Réglages : URL de l'instance (probablement https://n8nlouis.dcsys.tech, à confirmer avec Louis) et clé API n8n (Trousseau). La clé se crée dans n8n : Settings → n8n API.
  • Le Mac joint n8n, pas l'inverse : polling toutes les 5 s de l'API publique :
    • noms des workflows : GET /api/v1/workflows (cache 10 min) ;
    • exécutions récentes : GET /api/v1/executions avec filtres de statut et limit.
  • Mapping :
    • exécution en cours → tâche working (si l'API expose les exécutions en cours ; sinon n8n n'apparaît qu'aux erreurs et aux succès, c'est acceptable) ;
    • nouvelle exécution en erreur → alerte error, détail = nœud en échec + message (GET /api/v1/executions/{id}?includeData=true) ;
    • succès → mini-bonhomme finished 3 s en compact, sans ouvrir l'island (sinon trop de bruit), sauf réglage contraire.
  • Boutons :
    • « Relancer » → endpoint de retry de l'API publique (vérifier sa présence et son chemin dans le playground de l'instance). S'il n'existe pas : ouvrir l'exécution dans n8n.
    • « Ouvrir dans n8n » → ouvrir {URL}/workflow/{workflowId}/executions/{executionId} dans le navigateur par défaut.
  • Réglage « workflows suivis » : tous par défaut, liste à cocher.

3. Fichiers déposés

  • Glisser-déposer natif sur la panel (types fileURL). Copier les fichiers dans ~/Library/Application Support/NotchBuddy/inbox/ (c'est la phase uploading).
  • Vue choose :
    • Poser une question dessus → vue prompt avec une pastille du fichier. Envoi à l'API Claude (§5) : PDF en bloc document, images en bloc image, texte et code (≤ 200 Ko) en texte. Autres types : message « Je ne sais pas lire ce format, mais je peux l'envoyer par mail. »
    • Envoyer par mail → vue mail (§6).
  • Nettoyer l'inbox après 7 jours.

4. Attacher le bonhomme à une fenêtre

  1. Au lâcher, trouver la fenêtre sous le point : CGWindowListCopyWindowInfo(.optionOnScreenOnly), première fenêtre de couche 0 qui n'est pas la nôtre et contient le point. Récupérer app, titre, cadre.
  2. Afficher le halo : une panel transparente, non cliquable, posée sur le cadre de la fenêtre. Bordure conique arc-en-ciel de 3 pt qui tourne en 3 s (#FF6B5B → #F7B32B → #2DD4A7 → #38BDF8 → #A78BFA → #F472B6), voile multicolore en mode multiply qui respire (voir .attach du prototype), fondu d'entrée 600 ms. Son attach, émote Clin d'œil.
  3. Contexte envoyé à Claude :
    • capture de la fenêtre avec ScreenCaptureKit (SCScreenshotManager), redimensionnée à 1568 px de large max ;
    • si c'est Safari, Chrome, Arc ou Brave : URL et titre de l'onglet actif via AppleScript.
  4. Vue prompt avec la pastille « Safari, escale.fr » (app + domaine), focus sur le champ.
  5. Le halo reste pendant searching, disparaît quand le résultat s'affiche ou quand l'island se ferme.

Permissions : Enregistrement de l'écran (capture) et Automatisation (navigateur). Si refusées : on continue sans capture ou sans URL, et on le dit en une ligne dans la vue.


5. API Claude (recherche)

  • POST https://api.anthropic.com/v1/messages, en-têtes x-api-key, anthropic-version, content-type: application/json (versions à vérifier dans la doc).
  • Modèle par défaut : claude-sonnet-4-6, choisi dans Settings → Anthropic API ou depuis la puce de modèle dans la vue .prompt. La liste est récupérée à l'ouverture des réglages via GET /v1/models?limit=100 (en-têtes x-api-key et anthropic-version: 2023-06-01) ; si l'appel échoue ou qu'il n'y a pas de clé, une liste de secours est utilisée (claude-sonnet-4-6, claude-sonnet-5-5, claude-opus-5-5, claude-haiku-4-5-20251001). Un champ libre permet d'entrer n'importe quel identifiant. Si le modèle sauvegardé n'est pas dans la liste, le sélecteur reste sur « Custom… ». Dans le chat, si le modèle enregistré n'est pas dans la liste reçue, le premier dont l'identifiant contient « sonnet », sinon le premier de la liste.
  • Erreurs de l'API : affiche error.message au lieu du JSON brut. Pour un not_found_error, affiche « Model not found: <id>. Pick another one in Settings. »
  • Outil de recherche web côté serveur de l'API : l'identifiant de type à jour est dans la doc (au moment d'écrire, web_search_20250305) ; max_uses 5.
  • Prompt système (français) : répondre court, pour un affichage dans le notch, au format JSON strict :
    { "title": "…", "items": [ { "label": "…", "detail": "…", "url": "…" } ], "note": "…" }
    
    3 items maximum. Si le JSON est invalide : afficher le texte brut (3 lignes max) dans la vue result.
  • Contenu du message utilisateur : capture (bloc image) + « URL : … / Titre : … / Demande : … », ou fichier (§3) + demande, ou demande seule (onglet Demander).
  • Pendant l'appel : état searching, vue searching, texte scintillant. Réponse : état finished, vue result, émote Fier, son finish.
  • Boutons du résultat : « Ouvrir » (premier lien, seulement s'il est en http ou https ; sinon le bouton est grisé), « Copier » (texte), « Fermer ».
  • Erreur réseau ou clé invalide : état error, vue note avec la raison en une phrase et « Ouvre les réglages pour vérifier la clé ».
  • Micro (bouton du champ) : dictée SFSpeechRecognizer en fr-FR, sur l'appareil si possible. Optionnel (M9). Si la permission est refusée, masquer le bouton.

5bis. Autres fournisseurs du chat (Google AI, OpenAI)

Clés dans Settings → Chat — other providers (Trousseau : google-api-key, openai-api-key). La liste des modèles est récupérée à l'ouverture du chat selon le fournisseur :

  • Google AI (Gemini) : GET https://generativelanguage.googleapis.com/v1beta/openai/models (en-tête Authorization: Bearer <clé>) — on retire le préfixe models/, on filtre les modèles dont l'identifiant contient embed, imagen, veo, aqa, tts, audio ou live. Dans le chat, si le modèle enregistré n'est pas dans la liste reçue, le premier dont l'identifiant contient « flash », sinon le premier de la liste. Endpoint du chat : POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions.
  • OpenAI : GET https://api.openai.com/v1/models (en-tête Authorization: Bearer <clé>) — triés par champ created décroissant, on filtre les modèles dont l'identifiant contient embed, tts, whisper, dall-e, audio, realtime, moderat, codex, computer-use, transcribe, image, sora, babbage, davinci ou instruct. Dans le chat, si le modèle enregistré n'est pas dans la liste reçue, le premier dont l'identifiant contient « mini », sinon le premier de la liste. Endpoint du chat : POST https://api.openai.com/v1/chat/completions.

Ce qui est envoyé au fournisseur lors d'un échange : le texte saisi et la conversation en cours. Si une fenêtre est attachée : nom de l'app, titre et URL. Si un fichier est attaché : son nom seulement (le contenu d'un fichier ne part que chez Anthropic).

Voir le catalogue de pastilles dans docs/SPEC.md (section « Catalogue de pastilles ») pour les pastilles ai_google et ai_openai.


5ter. Modèles locaux (Ollama / LM Studio)

IDs de pastilles : ai_ollama (jaune #FACC15), ai_lmstudio (vert citron #A3E635)
Catégorie : AI for the chat
Plateforme : macOS uniquement

Connexion à un serveur local compatible OpenAI. Aucune clé d'API requise.

Connexion

Réglages → Chat → Local models → Connect. Coucou envoie une requête GET /v1/models au serveur. Si le serveur répond avec des modèles, l'URL est sauvegardée et le fournisseur apparaît dans le sélecteur de modèle. Les modèles d'embedding (nomic-embed-text, bge-*, etc.) sont filtrés automatiquement.

Streaming

Les messages sont diffusés token par token via POST /v1/chat/completions avec "stream": true. Les blocs de raisonnement (<think>…</think>, utilisés par des modèles comme DeepSeek-R1) sont masqués dans la bulle de chat tant que le bloc est ouvert, puis retirés de la réponse finale.

Pièces jointes

Les fichiers texte sont envoyés en ligne, tronqués à 24 000 caractères. Images et PDF : seul le nom du fichier est envoyé.

Déconnexion

Réglages → Chat → Local models → Disconnect. Efface l'URL sauvegardée et le cache des modèles. Si un fournisseur local était actif dans le chat, le chat revient sur Anthropic.


6. Mail (app Mail du Mac)

  • Vue mail : À (obligatoire, validation d'adresse), Objet (prérempli : nom du fichier), Message (optionnel, une ligne).
  • Envoi uniquement au clic sur « Envoyer », via AppleScript (NSAppleScript) sur Mail :
    tell application "Mail"
      set m to make new outgoing message with properties {subject:"…", content:"…", visible:false}
      tell m
        make new to recipient at end of to recipients with properties {address:"…"}
        make new attachment with properties {file name:(POSIX file "…")} at after the last paragraph of content
      end tell
      delay 1
      send m
    end tell
    
    Le delay laisse le temps à la pièce jointe d'être prise en compte (comportement connu de Mail). Info.plist : NSAppleEventsUsageDescription.
  • Succès : vue note « Mail envoyé à … », émote Clin d'œil, son send. Échec : état error avec la raison.

Pill Mail : recherche et filtres

  • Loupe dans l'en-tête de la carte : un champ de recherche. Mots libres (objet ou expéditeur), de: / from: pour l'expéditeur, objet: / subject: pour l'objet, guillemets pour une phrase (MailQuery.parse).
  • Filtres rapides sous l'en-tête : Tous · Non lus · Importants (drapeau de Mail) · Aujourd'hui. Pas de clause whose AppleScript (elle parcourt toute la boîte et fige Mail) : Coucou lit les 300 mails les plus récents de chaque boîte de réception par tranches de 50 (messages a thru b, 30 s au plus par lecture) et filtre en Swift (MailSearch.matches), 60 résultats au plus, les plus récents d'abord. Un mail ouvert est retrouvé par sa référence directe («class mssg» id N), la recherche dans la boîte ne sert qu'en secours. Au lancement de Mail, Coucou attend 30 s qu'il ait fini de se synchroniser.
  • « Voir plus » au bas de la liste : 12 mails de plus à chaque clic, jusqu'à 60.
  • Détail d'un mail : Important / Pas important (drapeau), Indésirable, et dans « … » : Toujours important (VIP), Toujours ignorer cet expéditeur (son adresse devient un mot banni).

Section Mail de la fenêtre Coucou (tri automatique)

  • Quatre pages, après Flow et Notch : Aperçu, Règles, Mots bannis, VIP. Réglages et journal en JSON dans Application Support/NotchBuddy/Mail (MailTriageStore).
  • Tri automatique, désactivé par défaut. Une fois activé, seuls les mails arrivés après l'activation sont regardés (autoSortSince), chacun une seule fois (seen.json). Le relevé de Mail tourne alors toutes les 60 s même si la pill est éteinte, seulement quand Mail est ouvert.
  • Ordre de décision (MailTriage.decide) : VIP (drapeau, jamais déplacé) → mots bannis dans l'expéditeur, l'objet ou le texte, mots entiers (indésirables) → règles dans l'ordre, la première qui correspond gagne. Le texte n'est lu que si un mot banni ou une règle « Texte » en a besoin (4 000 caractères).
  • Actions possibles : indésirables (statut indésirable + déplacement dans la boîte Junk/Spam du compte), important (drapeau), marquer comme lu, déplacer dans un dossier. Jamais de suppression.
  • Journal : chaque action avec sa raison et un bouton Annuler, qui retrouve le mail par son Message-ID (l'id de Mail change quand un mail est déplacé) et le remet en place.

Chat : actions sur les mails (bouton Mail du chat)

  • Bouton « Mail » à côté du choix du modèle, éteint à chaque lancement. Allumé, chaque message du chat part avec, en dessous, les 40 derniers mails des boîtes de réception, numérotés [n] (MailAgent.decorate) : comptes et adresses, date, lu ou non, expéditeur, objet. Les 8 plus récents ont leurs pièces jointes et le début du texte ; ceux que la demande nomme (expéditeur ou mot de l'objet) ont 3 000 caractères de texte.
  • Le prompt système reçoit MailAgentPrompt.instructions : l'IA répond en une phrase puis donne au plus un plan, bloc ```coucou-mail en JSON. Actions : flag / junk / read / move, reply (brouillon ouvert dans Mail, jamais envoyé), send (destinataires, objet, texte, pièces jointes d'un mail ou fichiers du Mac), merge (un mail par destinataire, chacun avec la page d'un PDF qui contient sa clé, ou la page dans l'ordre), save_attachments. Pas de suppression. Marche avec tous les fournisseurs du chat (clé API ou abonnement).
  • Le bloc n'est jamais affiché tel quel : la bulle montre une carte (MailPlanCard) qui prépare le plan (PDF enregistré depuis Mail, découpé page par page avec PDFKit, chaque page nommée « Plans - Bordeaux.pdf »), liste les mails, en rouge ceux sans page trouvée ou à l'adresse invalide (jamais envoyés).
  • Rien ne se passe sans clic : « M'envoyer un test » envoie le premier mail à l'adresse du premier compte, « Lancer (N) » démarre un compte à rebours de 5 s annulable, puis les étapes une par une, 1,2 s entre deux envois. Rapport : faits / échecs. Les envois sont listés dans Aperçu → Envoyés par Coucou.

6bis. WhatsApp (expérimental, build GitHub uniquement)

Pas d'API WhatsApp pour un compte perso : Coucou parle à une passerelle locale non officielle que l'utilisateur lance sur son Mac, GOWA (par défaut) ou OpenWA. Tout le code est sous #if !APPSTORE ; la pill integration_whatsapp (#25D366) est githubOnly.

  • Fichiers : WhatsAppModels.swift (boîte en mémoire, filtres, garde-fous, requête HTTP), WhatsAppGateway.swift (payloads et réponses des deux passerelles, HMAC), WhatsAppProvider.swift (GOWAProvider, OpenWAProvider), WhatsAppWebhook.swift (serveur 127.0.0.1), WhatsAppController.swift, WhatsAppViews.swift (carte, conversation, Réglages), WhatsAppGOWAProcess.swift (GOWA lancé par Coucou). Tests : scripts/test-whatsapp.sh.
  • GOWA : http://127.0.0.1:3000, auth basique user:pass facultative. Coucou prend l'appareil connecté, sinon crée coucou (POST /devices) ; QR = PNG de GET /devices/{id}/login, récupéré sur la passerelle elle-même ; webhook déclaré par PATCH /devices/{id}/webhook (événement message), signé X-Hub-Signature-256: sha256=<hex>. Messages : GET /chats, GET /chat/{jid}/messages ; envoi POST /send/message ; lu POST /message/{id}/read. Pas de liste de mentions : @<mon numéro> dans le texte.
  • OpenWA : http://127.0.0.1:2785/api, en-tête X-API-Key, moteur ENGINE_TYPE=baileys. Session prête, sinon coucou créée et démarrée ; QR = data-URL de GET /sessions/{id}/qr ; webhook POST /sessions/{id}/webhooks (message.received, message.sent), signé X-OpenWA-Signature. Il faut SSRF_ALLOWED_HOSTS=127.0.0.1 côté OpenWA, sinon il refuse l'adresse locale (Coucou passe alors au polling).
  • Temps réel : NWListener lié à 127.0.0.1 (port 47823 par défaut), pairs non-loopback refusés, signature HMAC-SHA256 vérifiée sur le corps brut avec un secret aléatoire du Keychain. Sans livraison depuis 5 min : polling toutes les 20 s. Statut toutes les 5 s tant que ce n'est pas lié, toutes les minutes ensuite, toutes les 30 s après une minute de panne. Réveil : on redemande tout.
  • Pill : une ligne par conversation (initiales, nom, aperçu, non-lus), médias en libellé. Nouveau message : émote happy, son pop (réglage son global), état finished comme Stripe (règles d'ouverture habituelles), seulement le nom de la conversation dans la pill, jamais le texte. Passerelle en panne deux fois de suite : badge rouge, rien de plus.
  • Répondre : clic → 10 derniers messages + champ (Entrée envoie, Maj+Entrée saut de ligne, Échap ferme ; le brouillon garde l'île ouverte). Réponse seulement dans une conversation déjà là, 4 096 caractères max, 6 par minute. Lu à l'ouverture (option) ou à la réponse, jamais à la réception.
  • Filtres : groupes muets sauf mention, chats ignorés (clic droit ou Réglages), Concentration via INFocusStatusCenter (demande la capability Communication Notifications ; sans elle, le réglage s'affiche indisponible).
  • Vie privée : rien d'autre que la passerelle locale (pas de photo de profil, elles sont sur les serveurs de WhatsApp), historique en mémoire seulement (20 messages par conversation), vidé à la fermeture ou à la désactivation, aucun contenu dans les logs ni sur disque. URL, identifiants et secret dans le Keychain.
  • Installer WhatsApp (un clic) : WhatsAppGOWAInstaller lit la dernière release de GOWA (api.github.com/repos/aldinokemal/go-whatsapp-web-multidevice/releases/latest), prend whatsapp_<version>_darwin_<arm64|amd64>.zip, vérifie son SHA-256 avec checksums-macos.txt (sinon le digest de GitHub ; sans empreinte, rien n'est installé), dézippe avec /usr/bin/ditto, range le binaire darwin-<arch> sous ~/Library/Application Support/Coucou/GOWA/gowa (chmod 755, sans quarantaine), puis active « Lancer GOWA automatiquement » et redémarre l'intégration : le QR suit. Redirections acceptées vers github.com et *.githubusercontent.com seulement. C'est le seul appel réseau hors passerelle, et seulement au clic.
  • Lancer GOWA automatiquement : processus enfant rest --host=127.0.0.1 --port=<port de l'URL> --auto-download-media=false, identifiant passé par APP_BASIC_AUTH (pas sur la ligne de commande), sortie vers /dev/null, dossier ~/Library/Application Support/Coucou/GOWA, arrêté à la fermeture de Coucou ou quand l'option est coupée, redémarré seulement si son binaire, son adresse ou son mot de passe change (en attendant que l'ancien soit parti), relancé s'il tombe (une fois par minute au plus). Aucune requête ne suit de redirection : rien ne part ailleurs que vers la passerelle.

7. Permissions macOS demandées (récapitulatif pour Louis)

Permission Pourquoi Quand
Automatisation → Mail envoyer les mails premier envoi
Automatisation → Terminal / iTerm / navigateur sauter au bon onglet, lire l'URL première utilisation
Automatisation → Musique (GitHub only) contrôler la lecture Apple Music première commande depuis le notch
Automatisation → Spotify (GitHub only) lire la position, le shuffle, le volume ; piloter la lecture activation de la pill Spotify, ou première ouverture de sa carte
Enregistrement de l'écran capturer la fenêtre attrapée première attache
Micro + Reconnaissance vocale (optionnel) dictée premier clic sur le micro
État de Concentration (GitHub only) WhatsApp reste discret pendant une Concentration activation de WhatsApp, si « Rester discret pendant une Concentration » est coché

Aucune permission Accessibilité nécessaire.