agent-mail : la boîte aux lettres de tes sessions Claude (et quand tu n'en as pas besoin)

🎯 Le résultat : tes sessions d'agents (Claude Code, Codex, Gemini CLI) s'envoient des messages qui attendent dans une boîte sur ton disque, même quand le destinataire est éteint. Et surtout : elles se réservent des fichiers, pour que deux agents n'écrivent jamais dans le même en même temps. Une commande, gratuit, open source, 100 % local.

🔴 Lis ça avant d'installer : dans beaucoup de cas tu n'en as pas besoin. Claude Code sait déjà envoyer un message à une autre session Claude ouverte sur ta machine, avec ListAgents et SendMessage, sans rien installer. Les auteurs d'agent-mail le disent eux-mêmes dans leur README : « If your sessions are all Claude Code, all spawned together, and all still running, you probably do not need this. » Si tes deux terminaux Claude sont ouverts en même temps, utilise le natif et passe ton chemin : je t'ai fait un guide complet dessus. Cette page-ci ne sert que si tu es dans un des quatre cas juste en dessous.

Alors quand est-ce que ça vaut le coup ?

Quatre cas, tirés de leur documentation. Il en suffit d'un.

1. Tu as lancé les sessions toi-même, chacune dans son projet, sans hiérarchie. Le natif marche entre une session cheffe et ses équipières qu'elle a lancées ; agent-mail parle à des sessions indépendantes.
2. Tout n'est pas Claude Code. Codex, Gemini CLI, Kimi Code utilisent les mêmes boîtes et les mêmes outils.
3. Le destinataire peut être éteint. C'est le cœur du truc : le message attend sur le disque et sera lu par une future session. Le natif exige que les deux soient vivantes au même moment.
4. Tu veux verrouiller des fichiers, pas des tâches. Un agent réserve un chemin, les autres savent qu'ils ne doivent pas y toucher.

Ce qu'il te faut

• Node 22.18 ou plus (node -v pour vérifier)
• Claude Code, et/ou Codex, Gemini CLI
• Rien d'autre : pas de clé API, pas de serveur à faire tourner, rien qui sort de ta machine

Le prompt à copier-coller dans Claude Code

TON RÔLE : tu fais tout le travail technique. Je ne tape aucune commande moi-même.
Tu poses tes questions UNE PAR UNE et tu attends ma réponse.

OBJECTIF : installer agent-mail (https://github.com/osteele/agent-mail), un bus de
messages local entre sessions d'agents, et me montrer qu'il marche.

ÉTAPE 1 — VÉRIFIER QUE J'EN AI BESOIN
Demande-moi d'abord : est-ce que mes sessions Claude sont toutes ouvertes en même
temps, dans le même projet ? Si oui, dis-moi d'utiliser ListAgents et SendMessage
natifs et ARRÊTE-TOI là. N'installe rien.

ÉTAPE 2 — LES PRÉREQUIS
Vérifie ma version de Node (il faut 22.18+). Si elle est trop vieille, dis-le-moi
et propose-moi la marche à suivre avant d'aller plus loin.

ÉTAPE 3 — L'INSTALLATION
Lance :
npx add-mcp github:osteele/agent-mail --args mcp --name agent-mail --global \
  --agent claude-code --agent codex
Explique-moi ce que la commande a écrit et où.

ÉTAPE 4 — LE TEST
Montre-moi que ça marche : lance `agent-mail status`, liste les sessions qui
écoutent, et explique-moi ce que chaque ligne veut dire.

ÉTAPE 5 — LE MODE D'EMPLOI
Donne-moi, en français et en trois lignes, comment demander à une session
d'envoyer un message à une autre, et comment réserver un fichier.

L'install à la main, si tu préfères

npx add-mcp github:osteele/agent-mail --args mcp --name agent-mail --global \
  --agent claude-code --agent codex

💡 --global écrit la config au niveau de ton compte et pas du projet courant : une session ouverte dans n'importe quel dossier reste joignable. Il n'y a rien à cloner et aucun service à laisser tourner : npx récupère agent-mail au démarrage de la session.

⚠️ L'étape que tout le monde rate : le « channel push »

Par défaut, une session ne reçoit pas le courrier toute seule : elle doit aller le chercher avec check_inbox. Pour que le message arrive tout seul dans son contexte, il faut trois choses alignées, et l'installation ne les fait pas pour toi.

1. Le plugin :

claude plugin marketplace add osteele/agent-mail
claude plugin install agent-mail@osteele-local

2. Les channels autorisés dans les réglages managés (/Library/Application Support/ClaudeCode/managed-settings.json) :

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "osteele-local", "plugin": "agent-mail" }
  ]
}

3. Chaque session lancée avec le channel chargé :

claude --channels=plugin:agent-mail@osteele-local

⚠️ Le fichier de l'étape 2 est dans un dossier système, donc il demande les droits admin. Moi je ne l'ai pas fait : mes sessions tournent en mode « je vais chercher mon courrier » et ça me va très bien. Commence sans, tu verras si ça te manque. agent-mail status te dit exactement où tu en es.

Ce que j'en fais vraiment, en toute transparence

Sur mes dernières sessions, agent-mail a été appelé 88 fois. La répartition m'a surpris :

Deux tiers de mes appels sont des verrous de fichiers, pas du courrier. Le nom du projet dit « mail », mais ce qui m'a vraiment servi c'est d'empêcher deux agents d'écrire dans le même fichier en même temps. Si tu fais tourner plusieurs sessions sur un même projet, c'est ça que tu viens chercher.

Il y a aussi un tableau de bord local sur http://127.0.0.1:8377/ quand le service tourne, et un écho vers Slack si tu le configures. Je n'utilise ni l'un ni l'autre pour l'instant.

Dépannage rapide

• « l'autre session ne reçoit rien » : normal sans le channel push. Dis à la session destinataire de regarder sa boîte (check_inbox), ou fais l'étape du dessus.
• « je ne trouve pas le nom de l'autre session » : les noms d'agent-mail (du style « Quick Bridge ») sont un annuaire séparé de celui du natif. On les liste avec list_sessions, pas avec ListAgents.
• « ça refuse de démarrer » : ta version de Node est probablement inférieure à 22.18.
• « un fichier reste bloqué » : la réservation est indicative, pas un verrou système. list_claims montre qui détient quoi, release_claim libère.

🙏 Crédit : agent-mail est un projet d'Oliver Steele (github.com/osteele/agent-mail), licence MIT. Je ne l'ai pas construit : je l'ai installé, je le fais tourner, et j'ai fait relire le dépôt à Claude avant de te l'envoyer.