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.
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 :
- Hooks Claude Code : https://code.claude.com/docs/en/hooks
- API Claude (Messages, outil de recherche web, modèles) : https://docs.claude.com/en/api/overview
- API publique n8n :
{URL de l'instance}/api/v1/docs(playground de l'instance de Louis)
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) etnb-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/. Voirdocs/AGENTS.mdpour 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érificationgetpeereid). 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--agentest fourni, le champcoucou_agent, puis l'envoie à l'app.- Si l'app ne répond pas en 300 ms,
nb-hooksort 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. Voirdocs/AGENTS.mdpour 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-hookattend 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 :hookSpecificOutputavecdecision.behavior=allowoudeny). 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é surPermissionRequest(issue GitHub anthropics/claude-code #19298). Tester allow et deny ; si deny ne marche pas, basculer la décision surPreToolUse(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
allowautomatiquement ensuite. Liste visible et supprimable dans les réglages. - Raccourcis Y / N quand la vue
approvalest ouverte.
Répondre aux questions (AskUserQuestion)
- Claude Code 2.1.85+ :
AskUserQuestionarrive enPreToolUse(avecmatcher: "AskUserQuestion"), non plus enPermissionRequest. Un hook dédié avec--asket un timeout de 130 s est requis danssettings.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. PermissionRequestpourAskUserQuestion: l'app répond{"permissionDecision":"ask"}immédiatement (no-op) et n'affiche pas de carte.PreToolUsegénéral pourAskUserQuestion: l'app ignore l'événement (pas de mise à jour de l'état.working).tool_input.questions: tableau de 1 à 4 questions, chacune avecquestion(texte),header(≤ 12 car.),options(2 à 4, chacunelabel+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
questionaffiche 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 (envoieask, 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… » : valeurString. - nb-hook.py
--ask: sidecision == 'answer'→ émethookSpecificOutputavechookEventName: "PreToolUse",permissionDecision: "allow"etupdatedInput: {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
- Lire
~/.claude/settings.json(le créer s'il n'existe pas). - Copier en
~/.claude/settings.json.bak-AAAAMMJJ-HHMM. - Fusionner : ajouter les hooks Notch Buddy sans toucher aux hooks existants. Chemin de
nb-hookentre guillemets (il contient un espace). - Montrer le diff à Louis, attendre son OK, écrire.
- 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_stringMultiEdit: listeedits, chaque entréeold_string → new_stringWrite: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, sinonNSWorkspace) - 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,oiddu 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) :
oidet état CI du commit HEAD surdefaultBranchRef
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/executionsavec filtres de statut etlimit.
- noms des workflows :
- 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
finished3 s en compact, sans ouvrir l'island (sinon trop de bruit), sauf réglage contraire.
- exécution en cours → tâche
- 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 phaseuploading). - Vue
choose:- Poser une question dessus → vue
promptavec une pastille du fichier. Envoi à l'API Claude (§5) : PDF en blocdocument, images en blocimage, 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).
- Poser une question dessus → vue
- Nettoyer l'inbox après 7 jours.
4. Attacher le bonhomme à une fenêtre
- 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. - 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.attachdu prototype), fondu d'entrée 600 ms. Sonattach, émote Clin d'œil. - 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.
- capture de la fenêtre avec ScreenCaptureKit (
- Vue
promptavec la pastille « Safari, escale.fr » (app + domaine), focus sur le champ. - 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êtesx-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 viaGET /v1/models?limit=100(en-têtesx-api-keyetanthropic-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.messageau lieu du JSON brut. Pour unnot_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_uses5. - Prompt système (français) : répondre court, pour un affichage dans le notch, au format JSON strict :
3 items maximum. Si le JSON est invalide : afficher le texte brut (3 lignes max) dans la vue{ "title": "…", "items": [ { "label": "…", "detail": "…", "url": "…" } ], "note": "…" }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, vuesearching, texte scintillant. Réponse : étatfinished, vueresult, émote Fier, sonfinish. - 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, vuenoteavec la raison en une phrase et « Ouvre les réglages pour vérifier la clé ». - Micro (bouton du champ) : dictée
SFSpeechRecognizerenfr-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êteAuthorization: Bearer <clé>) — on retire le préfixemodels/, on filtre les modèles dont l'identifiant contientembed,imagen,veo,aqa,tts,audiooulive. 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êteAuthorization: Bearer <clé>) — triés par champcreateddécroissant, on filtre les modèles dont l'identifiant contientembed,tts,whisper,dall-e,audio,realtime,moderat,codex,computer-use,transcribe,image,sora,babbage,davinciouinstruct. 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 :
Letell 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 telldelaylaisse 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, sonsend. Échec : étaterroravec 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
whoseAppleScript (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-mailen 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 basiqueuser:passfacultative. Coucou prend l'appareil connecté, sinon créecoucou(POST /devices) ; QR = PNG deGET /devices/{id}/login, récupéré sur la passerelle elle-même ; webhook déclaré parPATCH /devices/{id}/webhook(événementmessage), signéX-Hub-Signature-256: sha256=<hex>. Messages :GET /chats,GET /chat/{jid}/messages; envoiPOST /send/message; luPOST /message/{id}/read. Pas de liste de mentions :@<mon numéro>dans le texte. - OpenWA :
http://127.0.0.1:2785/api, en-têteX-API-Key, moteurENGINE_TYPE=baileys. Session prête, sinoncoucoucréée et démarrée ; QR = data-URL deGET /sessions/{id}/qr; webhookPOST /sessions/{id}/webhooks(message.received,message.sent), signéX-OpenWA-Signature. Il fautSSRF_ALLOWED_HOSTS=127.0.0.1côté OpenWA, sinon il refuse l'adresse locale (Coucou passe alors au polling). - Temps réel :
NWListenerlié à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, sonpop(réglage son global), étatfinishedcomme 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) :
WhatsAppGOWAInstallerlit la dernière release de GOWA (api.github.com/repos/aldinokemal/go-whatsapp-web-multidevice/releases/latest), prendwhatsapp_<version>_darwin_<arm64|amd64>.zip, vérifie son SHA-256 avecchecksums-macos.txt(sinon ledigestde GitHub ; sans empreinte, rien n'est installé), dézippe avec/usr/bin/ditto, range le binairedarwin-<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é parAPP_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.