Désinstaller Headroom (et quoi utiliser à la place)

Pour désinstaller Headroom, défaites chaque chose qu'il a mise en place, dans cet ordre, tant que la commande headroom existe encore : retirez tout déploiement persistant, faites un unwrap de chaque agent, retirez le serveur MCP, puis supprimez le paquet et ses données. Il n'existe pas encore de commande headroom uninstall unique.

L'ordre compte, car c'est la CLI qui restaure. Supprimez le paquet en premier et il vous reste à corriger les configurations d'agents à la main.

La documentation de Headroom le dit sans détour : « A full teardown currently spans several commands » (une désinstallation complète demande actuellement plusieurs commandes), suivi dans l'issue #748, qui propose une commande headroom uninstall consolidée. Cette issue était toujours ouverte quand j'ai vérifié.

Étapes tirées du README de Headroom et de sa documentation sur docs.headroomlabs.ai, relus le 15 octobre 2026. Les commandes peuvent changer d'une version à l'autre : vérifiez headroom --help sur la vôtre.

Qu'est-ce que Headroom installe sur votre machine ?

Jusqu'à six types de modifications, selon les commandes que vous avez lancées. Faites votre inventaire avant de commencer, car chacune a sa propre étape de suppression.

Deux ajouts s'oublient facilement. headroom learn écrit ses corrections dans CLAUDE.local.md par défaut, ou dans CLAUDE.md, AGENTS.md, GEMINI.md ou GROK.md. Et le script d'installation Docker place un wrapper headroom dans ~/.local/bin ou ~/bin et modifie vos fichiers de démarrage du shell.

Étape 1 : retirer tout déploiement persistant

Si vous avez lancé un jour headroom deploy ou headroom install apply, commencez par headroom install remove. Vérifiez avec headroom install status.

D'après la documentation, le install remove final restaure l'instantané d'origine des configurations d'agents modifiées et supprime ses fichiers de sauvegarde. C'est la commande de cycle de vie du profil de déploiement derrière le service, la tâche de surveillance planifiée ou le conteneur Docker qui maintenait le proxy en vie. Si vous n'avez jamais lancé que headroom proxy dans un terminal, arrêtez-le avec Ctrl+C et passez cette étape.

Étape 2 : faire un unwrap de chaque agent encapsulé

Lancez headroom unwrap <tool> une fois par agent. Chaque encapsulation se défait séparément : il faut donc vous souvenir des agents concernés.

Le README liste claude, copilot, codex, grok, kimi, omp, opencode, openclaw et zcode. La documentation ajoute vscode-claude et vscode pour les intégrations VS Code, ainsi que grok-build. D'après la documentation, unwrap restaure la configuration d'avant l'encapsulation à partir d'une sauvegarde quand il y en a une, et retire l'enregistrement de Serena ajouté par wrap.

Faites-le avant l'étape 4. La documentation prévient que dans VS Code, tant que le proxy est arrêté, les requêtes échouent (« fail closed ») au lieu de contourner Headroom. C'est l'unwrap qui rétablit l'accès direct.

Étape 3 : retirer le serveur MCP

Lancez headroom mcp uninstall. C'est un enregistrement distinct de wrap, créé par headroom mcp install.

Listez ensuite vos serveurs MCP (pour Claude Code, claude mcp list) et vérifiez qu'aucune entrée headroom ne reste. Si vous avez gardé Serena volontairement, laissez-le.

Étape 4 : supprimer le paquet

Désinstallez le paquet comme vous l'avez installé. La CLI n'est livrée que dans le paquet PyPI headroom-ai.

Si vous avez installé le paquet npm en global, ajoutez -g ; l'issue #748 cite le paquet npm global comme celui qu'on oublie. Si vous avez utilisé le script d'installation Docker, retirez le wrapper headroom de ~/.local/bin ou ~/bin, supprimez le bloc PATH ajouté à vos fichiers de démarrage du shell, et retirez l'image avec docker rmi ghcr.io/headroomlabs-ai/headroom:latest. La documentation décrit ce que cet installeur ajoute ; elle ne documente pas de commande pour le retirer.

Étape 5 : nettoyer données et variables d'environnement

Supprimez ~/.headroom une fois sûr de ne plus avoir besoin de l'historique des économies. C'est irréversible.

Cherchez ensuite ce que vous avez réglé à la main. Si vous avez suivi les instructions du proxy, vous avez peut-être exporté ANTHROPIC_BASE_URL=http://localhost:8787 ou OPENAI_BASE_URL dans votre profil de shell, plus des variables HEADROOM_*. Retirez ces lignes et ouvrez un nouveau terminal. Enfin, relisez CLAUDE.local.md, CLAUDE.md ou AGENTS.md pour repérer les corrections écrites par headroom learn, et ne gardez que ce qui vous sert encore.

Comment vérifier qu'il ne reste rien ?

Lancez ces vérifications ; aucune ne doit rien afficher.

Vérifiez aussi vos fichiers de démarrage du shell à la recherche d'un bloc PATH Headroom, et les fichiers *.headroom-backup restés à côté des configurations d'agents. Une sauvegarde qui subsiste signifie que la restauration de cet agent n'a pas tourné : comparez-la au fichier actif avant de supprimer quoi que ce soit.

Un signe que c'est réussi : la commande /remote-control de Claude Code revient. La documentation de Headroom note qu'elle disparaît quand ANTHROPIC_BASE_URL pointe vers un autre hôte que api.anthropic.com.

Pourquoi on retire Headroom

Surtout parce qu'il n'a pas rendu les sessions moins chères. Sur le benchmark ouvert THOL, Headroom a rendu les sessions longues 52,8 % plus chères que le même agent sans outil, un écart hors du bruit d'une exécution à l'autre : nettement plus cher.

Divulgation : je maintiens THOL et je développe Tokenade. Le benchmark est public et reproductible, mais ce n'est pas un tiers indépendant. Son fonctionnement est expliqué sur la page THOL.

La compression message par message fonctionne ; THOL mesure la facture, pas la cause. Dans une vraie boucle d'agent, tout ce qui pousse l'agent à faire des étapes en plus coûte plus qu'il n'économise, car chaque étape renvoie tout l'historique.

Quoi utiliser à la place : Tokenade

Tokenade est le remplaçant dont la baisse de facture est mesurée : sur les sessions longues, une session coûte 39 % de moins qu'avec l'agent seul. Il agit à l'autre bout du tuyau : il allège ce que renvoient les outils (sorties de commandes, lectures de fichiers, résultats MCP) avant que cela n'atteigne le modèle, au lieu de réécrire chaque message.

L'installation tient en deux commandes :

tokenade install détecte vos agents et branche leurs hooks : par défaut, aucun proxy et aucune URL de base à changer. Un proxy LLM local optionnel existe pour les agents que les hooks n'atteignent pas ; il démarre lui aussi sur le port 8787, alors faites les vérifications ci-dessus avant de l'activer. La compaction tourne sur votre machine. Le guide complet est dans la documentation d'installation.

Pour mémoire, la désinstallation tient en une commande : tokenade uninstall, et tokenade uninstall --dry-run liste d'abord ce qu'elle retirerait. Tokenade est gratuit et open source (MIT/Apache-2.0).

Si vous préférez comparer d'abord, Alternatives à Headroom classe six options sur les mêmes critères, et Tokenade vs Headroom met les deux côte à côte.

FAQ

Existe-t-il une commande headroom uninstall ?

Pas encore. La documentation de Headroom indique qu'une désinstallation complète demande plusieurs commandes et renvoie à l'issue #748, qui propose une commande headroom uninstall unique. En attendant, utilisez install remove, unwrap, mcp uninstall puis votre gestionnaire de paquets, dans cet ordre.

pip uninstall headroom-ai supprime-t-il tout ?

Non. Il retire la CLI, mais pas les configurations d'agents modifiées par wrap, l'enregistrement MCP, un service ou conteneur persistant, ni ~/.headroom. Pire : une fois la CLI partie, vous ne pouvez plus lancer headroom unwrap. Faites donc les étapes 1 à 3 d'abord.

Claude Code ne marche plus après avoir retiré Headroom. Pourquoi ?

Quelque chose le dirige encore vers le proxy du port 8787. Cherchez ANTHROPIC_BASE_URL dans votre environnement, votre profil de shell et le bloc env de ~/.claude/settings.json. Si la CLI est encore installée, headroom unwrap claude (ou vscode-claude) restaure les valeurs précédentes.

Comment retirer Headroom de VS Code ?

Lancez headroom unwrap vscode-claude pour l'extension Claude Code et headroom unwrap vscode pour Copilot. Si vous avez passé --settings-file à l'installation, passez la même option à l'unwrap. Les autres réglages de VS Code sont conservés, d'après la documentation.

Faut-il supprimer ~/.headroom ?

Oui, si vous en avez fini avec Headroom. Il contient la configuration, les logs, les statistiques d'économies et son stockage local de compression. Copiez d'abord ce que vous voulez garder : la suppression est définitive.

Voir aussi :

• Alternatives à Headroom — six options, classées sur le coût de session mesuré
• Tokenade vs Headroom — les deux côte à côte
• headroom vs rtk — compression de messages entiers face au filtrage du shell
• Meilleurs optimiseurs de tokens pour Claude Code — tout le terrain, même méthode
• Installer Tokenade — trois commandes