L'intégration Claude Code d'iTerm2 : ce qu'elle fait et comment l'installer

Des gens tapent « iterm2 claude code » dans Google et tombent sur notre comparaison entre AgentsRoom et iTerm2. Cette page répond à une autre question. Celle-ci répond à la leur : ce que fait l'intégration Claude Code d'iTerm2, comment on l'installe, ce qu'elle change sur ton Mac, et où elle s'arrête.

On construit AgentsRoom, une app pour faire tourner des agents de code, donc on n'est pas neutres. On a écrit cet article à partir des pages d'iTerm2, lues le 19 octobre 2026 : la page de l'intégration Claude Code, la documentation de Session Status, et les notes de version d'iTerm2 3.7.0 à 3.7.6. On n'a pas installé iTerm2 pour l'écrire. Tous les noms de menus ci-dessous sont repris de ces pages, en anglais, comme dans l'app.

La réponse courte

• Ce que c'est : une installation facultative livrée avec iTerm2 3.7.0 (8 septembre 2026). Elle branche Claude Code sur le Session Status d'iTerm2 : chaque session Claude montre si elle travaille, si elle t'attend ou si elle a fini.
• Comment l'installer : iTerm2 > Install Claude Code Integration, puis suis la fenêtre d'installation.
• Ce qu'il faut : Claude Code installé sous la commande claude, l'API Python d'iTerm2 activée, et macOS 13 ou plus récent pour iTerm2 3.7.6.
• Ce que tu obtiens : un statut sur chaque onglet, la liste de toutes les sessions triées par urgence, un workgroup Claude Code avec Chat, Diff et Code Review côte à côte, et des commentaires de revue que tu peux renvoyer à Claude.
• Codex : suivi depuis la 3.7.5 (14 octobre 2026), à configurer à la main.
• Pour revenir en arrière : iTerm2 > Uninstall Claude Code Integration.

Ce que l'installation change sur ton Mac

L'entrée de menu ouvre une fenêtre d'installation en cinq étapes. Toutes sont facultatives sauf la première.

1. Enable Python API. Obligatoire. Le hook s'en sert pour envoyer chaque statut à iTerm2, et Code Review pour ajouter ses remarques au panneau Clippings. macOS te demande de confirmer.
2. Install Hook. Ajoute des hooks dans ~/.claude/settings.json. Le hook pointe vers un chemin stable dans le dossier de configuration d'iTerm2.
3. Show Toolbelt. Revient à View > Toolbelt > Show Toolbelt, ou Cmd+Shift+B.
4. Install Workgroup. Ajoute un workgroup Claude Code, modifiable ensuite dans Settings > Arrangements > Workgroups.
5. Auto-Enter Workgroup. Tu choisis les profils qui reçoivent les triggers d'entrée et de sortie.

Deux endroits changent donc : le fichier de réglages de Claude Code, et les réglages d'iTerm2 lui-même (API Python, toolbelt, Session Status, le workgroup, les triggers sur les profils choisis).

Deux correctifs de la 3.7.5 comptent si ta configuration n'est pas celle par défaut. L'installateur respecte maintenant $CLAUDE_CONFIG_DIR, donc le statut fonctionne quand Claude Code range ses réglages hors de ~/.claude. Et il n'écrase plus un settings.json qui contient une erreur de syntaxe, ni ne remplace par un fichier ordinaire celui qui est un lien symbolique. Avant la 3.7.5, le premier cas effaçait tes autres réglages Claude Code. Si tu es sur une 3.7 plus ancienne, mets à jour avant d'installer.

Si tu ne l'as pas installée, iTerm2 te la propose une fois : un bandeau demande « Want to try the Claude Code integration? » quand Claude tourne. Try It Now ouvre le workgroup jusqu'à l'arrêt de Claude. L'installation depuis le menu la rend permanente.

Ce que tu vois : Session Status

Chaque session Claude envoie un état, affiché sur son onglet par un sous-titre, un point de couleur et une couleur de sous-titre :

Done et error se rangent juste sous waiting, et une touche pressée dans la session les marque comme vus. Avec un Claude Code récent, une session reste en working tant que ses agents ou tâches d'arrière-plan tournent : une courte pause ne la fait pas passer en idle. Et depuis la 3.7.5, Échap pour interrompre Claude remet le statut en idle. Avant, l'onglet restait en working jusqu'à ta requête suivante.

Tu lis ces états à trois endroits :

• L'onglet de chaque session.
• L'outil Session Status, dans View > Toolbelt > Session Status. Il liste toutes les sessions avec leur point et leur libellé, met en tête celles qui ont besoin de toi, et saute à une session quand tu cliques sur sa ligne. Une ligne peut porter un détail, comme l'outil qui attend une permission ou un extrait du dernier message de Claude. Tu peux mettre une ligne en sommeil (Snooze) : elle passe sous un séparateur jusqu'à ce que son statut change.
• Le Cockpit, dans Window > Cockpit, un panneau flottant avec le statut de toutes les fenêtres. Depuis la 3.7.5, il peut aussi envoyer une commande à plusieurs sessions à la fois.

Pour être prévenu, Window > Notify on Status Change t'alerte au prochain changement de statut d'une session ou de toute la fenêtre.

Le workgroup Claude Code

Un workgroup transforme une session en un groupe de sessions liées, qu'iTerm2 appelle des peers. Le workgroup Claude Code en ajoute trois à côté de la session principale :

• Chat : la conversation principale avec Claude.
• Diff : les changements de ton arbre de travail, côte à côte.
• Code Review : une session à part qui relit ces changements.

Tu passes d'un peer à l'autre depuis la barre d'outils du workgroup. Les commentaires de revue sont rangés en clippings, pour être renvoyés à Claude dans le chat. Depuis la 3.7.5, cette barre peut aussi afficher une jauge AI Usage avec l'usage de la session et de la semaine de ton abonnement Claude.

Avec Auto-Enter, des triggers surveillent le processus claude : le workgroup s'ouvre quand claude démarre dans un des profils choisis et se referme quand le claude de la session principale s'arrête. Seule la sortie de la session principale compte : arrêter claude dans un peer laisse le workgroup ouvert. Tu peux aussi y entrer à la main avec Shell > Workgroups > Claude Code, et en sortir avec Shell > Workgroups > Exit Workgroup.

Quand le statut ne se met plus à jour

La panne la plus fréquente ne vient pas d'iTerm2. Claude Code peut réécrire ~/.claude/settings.json et perdre le hook cc-status. L'onglet ne change alors plus d'état, sans prévenir.

iTerm2 vérifie au lancement suivant de Claude et propose de remettre le hook : choisis Reinstall, ou Not Now. Tu peux le faire toi-même avec iTerm2 > Reinstall Claude Code Integration. Depuis la 3.7.5, si tu as modifié les commandes du hook pour utiliser $HOME, ~ ou un script intermédiaire, la réinstallation garde tes commandes au lieu d'ajouter des doublons.

Deux autres cas ressemblent à une panne et n'en sont pas :

• Une session tmux ordinaire. Depuis la 3.7.5, iTerm2 ne remonte plus le statut de Claude Code depuis un panneau d'une session tmux qui n'utilise pas tmux Integration, parce qu'il ne sait pas quel onglet affiche ce panneau. Les sessions dans des panneaux tmux Integration, elles, sont listées.
• Une vieille 3.7. Le correctif d'Échap, celui de CLAUDE_CONFIG_DIR et celui des liens symboliques sont tous arrivés en 3.7.5. Vérifie d'abord ta version.

Pour tout retirer, iTerm2 > Uninstall Claude Code Integration enlève le hook, le workgroup et les triggers de tous les profils. Il demande s'il faut garder l'API Python, au cas où d'autres scripts s'en servent.

Codex et les autres CLI d'agents

L'intégration est faite pour Claude Code. Depuis la 3.7.5, l'outil Session Status peut aussi suivre Codex CLI, mais sans installateur : les notes de version disent de modifier ~/.codex/hooks.json et de faire pointer chaque événement de hook vers l'outil cc-status du dossier utilities des Resources d'iTerm2.app, avec --agent codex, et un timeout de 3 sur les hooks Interrupt et SessionEnd. Les notes ne donnent pas la liste des événements : c'est la documentation des hooks de Codex qui l'a.

Pour les autres CLI, pas d'intégration, mais une porte d'entrée. Un programme peut poser son propre statut par une séquence d'échappement (OSC 21337, ou le Program Status Protocol, OSC 7501, depuis la 3.7.5), par la commande it2 session set-status, ou par un trigger Set Tab Status qui compare sa sortie à une expression régulière (Settings > Profiles > Advanced > Triggers). Si ton CLI a des hooks, un petit script qui appelle it2 depuis ces hooks fait l'essentiel. Notre guide des événements de hook de Claude Code montre quel événement part à quel moment, et c'est ce qu'il te faut pour choisir les bons.

Sur ton téléphone : iTerm2 Buddy

iTerm2 3.7.0 a aussi apporté iTerm2 Buddy, une app iOS qui s'appaire avec ton Mac en scannant un QR code. Elle montre une session en direct, reçoit les alertes d'iTerm2 en notifications push et te laisse poursuivre le chat IA d'iTerm2. Depuis la 3.7.5, la liste des sessions se met à jour en direct, l'outil it2 peut envoyer une notification push au téléphone appairé, et quand iTerm2 affiche un avertissement pendant ton absence, Buddy reste connecté, l'affiche et te laisse y répondre. Les autres fenêtres de dialogue ne se règlent pas depuis le téléphone. Il n'existe pas de version Android. Notre page de comparaison donne les détails qu'on a vérifiés sur Buddy en septembre.

Où elle s'arrête

• Sur Mac seulement. iTerm2 est une app macOS, et la 3.7.6 demande macOS 13 ou plus récent.
• Claude Code d'abord. Codex est pris en charge à la main depuis la 3.7.5, le reste se fait soi-même.
• Un terminal sur un Mac. Le statut vit dans cet iTerm2. Une session sur un autre ordinateur, ou dans un autre terminal, n'apparaît pas dans la liste.
• L'API Python reste activée. C'est le prix du hook. Des scripts locaux peuvent alors piloter iTerm2, et c'est pour ça que macOS te demande de confirmer.
• Une mise à jour de Claude Code peut faire sauter le hook. Reinstall le remet, mais rien ne te prévient avant que l'onglet se taise, jusqu'au lancement suivant de Claude.

Rien de tout ça n'est un défaut pour quelqu'un qui vit dans iTerm2 et fait tourner Claude Code dans quelques onglets. C'est un terminal qui a appris à très bien lire un agent.

Ce que fait AgentsRoom à côté

AgentsRoom part de l'agent au lieu de l'onglet du terminal. Chaque agent a un statut dans la liste des agents (en cours, terminé, en attente de réponse, inactif), quel que soit celui des 14 CLI pris en charge qui le fait tourner. Les mêmes statuts te suivent dans l'app mobile sur iOS et Android, et l'app tourne sur macOS, Windows et Linux.

Beaucoup gardent les deux : iTerm2 pour le shell, le SSH et les scripts, et une app d'agents pour les agents. Si tu choisis encore ton terminal pour travailler avec des agents, cette comparaison des terminaux passe en revue tmux, Ghostty, Warp et cmux.

Questions fréquentes

iTerm2 a-t-il une intégration Claude Code ?

Oui, depuis iTerm2 3.7.0 (8 septembre 2026). Elle est facultative et réversible. Elle ajoute à Claude Code des hooks qui envoient l'état de chaque session à iTerm2, qui l'affiche sur l'onglet et dans l'outil Session Status, et elle ajoute un workgroup Claude Code avec les sessions Chat, Diff et Code Review. Les commentaires de revue sont rangés en clippings, que tu peux renvoyer à Claude.

Comment installer l'intégration Claude Code dans iTerm2 ?

Choisis iTerm2 > Install Claude Code Integration. Une fenêtre te guide en cinq étapes : Enable Python API (obligatoire), Install Hook, Show Toolbelt, Install Workgroup et Auto-Enter Workgroup. Claude Code doit être installé et se lancer avec la commande claude. iTerm2 3.7.6 demande macOS 13 ou plus récent.

Pourquoi le statut Claude Code ne se met plus à jour dans iTerm2 ?

Le plus souvent, Claude Code a réécrit ~/.claude/settings.json et perdu le hook cc-status. iTerm2 s'en aperçoit au lancement suivant de Claude et propose Reinstall. Tu peux aussi choisir iTerm2 > Reinstall Claude Code Integration. Si tu ranges les réglages de Claude Code hors de ~/.claude avec CLAUDE_CONFIG_DIR, passe à iTerm2 3.7.5 ou plus récent, qui respecte cette variable.

Le Session Status d'iTerm2 fonctionne-t-il avec Codex ?

Depuis iTerm2 3.7.5, l'outil Session Status peut aussi suivre Codex CLI, mais sans installateur. Tu modifies toi-même ~/.codex/hooks.json et tu fais pointer les événements de hook vers l'outil cc-status livré dans iTerm2.app, avec --agent codex. Les autres CLI d'agents n'ont pas d'intégration : ils peuvent envoyer un statut par les séquences d'échappement d'iTerm2, la commande it2 ou un trigger.

Pourquoi l'intégration Claude Code d'iTerm2 a-t-elle besoin de l'API Python ?

C'est par l'API Python que le hook transmet chaque statut à iTerm2, et que les remarques de Code Review arrivent dans le panneau Clippings. L'installation ne va pas plus loin tant qu'elle n'est pas activée, et macOS te demande de confirmer. À la désinstallation, iTerm2 demande s'il faut garder l'API Python, parce que d'autres scripts peuvent s'en servir.

Existe-t-il une intégration Claude Code d'iTerm2 pour Windows ou Linux ?

Non. iTerm2 est une app macOS : l'intégration, l'outil Session Status et le workgroup n'existent que sur Mac. Sous Windows ou Linux, il te faut un autre terminal ou une app qui suit elle-même les sessions de tes agents.