RTK 1.0 en production : installer, mesurer, se protéger

Un jour, sur ce projet, le hook RTK s'est retrouvé au milieu d'un enchaînement de git stash et de git reset. L'agent a continué sans broncher, avec une image fausse de l'état du dépôt, et des modifications non commitées ont disparu de l'arbre de travail. Je les ai retrouvées avec git fsck --unreachable, en fouillant les blobs orphelins. Depuis, toute opération git qui modifie l'état passe par rtk bypass. Je n'ai pas désinstallé l'outil pour autant.

Parce que RTK fait ce qu'il promet. RTK (Rust Token Killer) est un binaire en ligne de commande qui condense la sortie des commandes shell avant qu'elle n'entre dans le contexte de Claude Code. Le dépôt rtk-ai/rtk dépasse les 83 000 étoiles, et la 1.0 est sortie le 13 octobre 2026. Cet article te donne de quoi l'installer en connaissance de cause : ce que le hook fait vraiment, comment mesurer un gain qui n'est pas celui du README, où la compression coûte de l'exactitude, et ce que change la licence de la 1.0.

Que fait RTK, et que ne touche-t-il pas ?

Un hook PreToolUse sur l'outil Bash réécrit les commandes de l'agent : git status devient rtk git status. RTK exécute la vraie commande, puis filtre, regroupe, déduplique et tronque la sortie avant que le modèle la lise. L'agent n'écrit jamais rtk lui-même. Le hook ne s'applique qu'à l'outil Bash : les outils natifs Read, Grep et Glob ne passent pas par lui. Si ton agent lit surtout avec Read, RTK ne touche que la partie shell de ta consommation.

La 1.0 apporte trois changements qui comptent au quotidien. rtk proxy <cmd> devient rtk bypass <cmd>, l'ancien nom restant un alias. L'option --ultra-compact disparaît. Et rtk gain exclut désormais de son taux principal les sorties surdimensionnées. S'y ajoutent un moteur de pipelines, un proxy LLM et un changement de licence, détaillé plus bas. Ici, on reste sur le hook shell, qui est le cœur de l'outil.

Comment installer RTK et brancher le hook de Claude Code ?

# Attention : le crate crates.io « rtk » est un autre projet, pas de cargo install rtk
brew install rtk
# ou : curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

rtk --version   # 1.0.x
rtk gain        # doit afficher un tableau de bord ; sinon, mauvais paquet

# Hook pour Claude Code, au niveau utilisateur (demande confirmation)
rtk init -g
# variantes : --auto-patch, --no-patch, --hook-only, --uninstall

En 1.0, le hook est un binaire natif : plus de script ~/.claude/hooks/rtk-rewrite.sh, plus de dépendance à jq. Voici le bloc résultant dans ~/.claude/settings.json, relevé sur ma configuration. Si tu migres depuis une 0.x, relance rtk init -g, sinon tu gardes un script qui n'est plus maintenu.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "rtk hook claude" }]
      }
    ]
  }
}

Deux vérifications sans rien modifier : rtk init --show confirme que le hook est configuré, et rtk hook check "git status" affiche à blanc la réécriture que le hook appliquerait. Redémarre Claude Code après l'installation : les hooks sont lus au démarrage de la session. Un hook mal branché échoue en silence, et tu crois économiser alors que rien ne se passe.

Que change RTK sur une vraie commande ?

Le dry-run rtk hook check montre la table de réécriture sans rien exécuter. Relevé sur ce dépôt :

git status                                  -> rtk git status
git stash push -m x                         -> rtk git stash push -m x
git push origin main                        -> rtk git push origin main
git log main..HEAD                          -> rtk git log main..HEAD
cat README.md                               -> rtk read README.md
vendor/bin/phpunit                          -> rtk phpunit
git status && git stash                     -> rtk git status && rtk git stash
git reset --hard HEAD~1                     -> No rewrite
docker compose exec php vendor/bin/phpunit  -> No rewrite

Premier enseignement pour une stack PHP conteneurisée : vendor/bin/phpunit lancé sur l'hôte passe par le filtre PHPUnit, mais docker compose exec php vendor/bin/phpunit n'est pas réécrit, car la commande commence par docker. Si tu travailles « Docker d'abord », tu perds le filtre qui rapporte le plus ; le hook maison présenté dans l'article sur les leviers natifs couvre ce cas. Deuxième enseignement : git stash est réécrit, git reset ne l'est pas. On y revient.

Sur un git log, le gain est visible : en brut, chaque commit occupe six à huit lignes (hash, auteur, date, message, trailers). Avec rtk git log, il tient en deux lignes, avec un sujet coupé vers 70 caractères. On voit les quatre stratégies du README à l'œuvre : filtrage du bruit, regroupement, troncature, déduplication. Ici, la perte est bénigne. Le problème apparaît quand la troncature touche l'information qui décide d'une action.

Comment mesurer l’économie réelle avec rtk gain ?

rtk gain mesure uniquement la baisse du volume de sortie shell, et estime les tokens à octets ÷ 4 : RTK n'embarque pas de tokenizer. Le pourcentage est cohérent, puisque le même estimateur s'applique avant et après ; les valeurs absolues ne correspondent pas à ta facture. Le projet annonce 60 à 90 % d'économie. Mon relevé sur 90 jours, sur ma machine :

Total commands:  18826
Input tokens:    10.0M  /  Output tokens: 6.9M
Tokens saved:    3.1M (31.5%)
Excluded:        334 oversized outputs
Top: rtk find 99.9 % · rtk grep 67.6 % · rtk read 52.8 %

Le chiffre honnête, chez moi, est donc 31,5 % de volume de sortie shell en moins, pas 60 à 90 %. Le haut de la fourchette vaut pour des commandes bavardes (find, ps, docker ps), pas comme moyenne. Et ce volume n'est qu'une fraction de ce que tu envoies au modèle : prompt système, historique et lectures de fichiers n'en profitent pas. Quelques options utiles pour creuser :

rtk gain --project     # filtrer sur le projet courant
rtk gain --daily       # ou --weekly, --monthly, --all --format json
rtk gain --failures    # commandes retombées en exécution brute
rtk gain --recalls     # fréquence à laquelle l'agent récupère une sortie élidée
rtk discover           # commandes qui auraient pu être filtrées

Pour parler de coût, il faut recouper : rtk gain donne le volume shell filtré, /usage et ccusage donnent la consommation réelle, comme expliqué dans l'article sur le suivi de consommation. Les deux ne se comparent pas directement. L'issue #582 (« +18 % de coût ») illustre l'enjeu : elle reposait sur un seul run. Les mainteneurs ne l'ont pas reproduite sur 20 runs alternés (−7,5 % de tokens de sortie en moyenne), et l'ont fermée. Conclusion prudente : RTK ne fait pas exploser les coûts de façon reproductible, mais le gain réel dépend de ta charge de travail. La méthode pour le mesurer proprement fera l'objet d'un article dédié de la série.

Quels pièges avec git et les sorties condensées ?

La compression est lossy par conception. Ce n'est pas un défaut de RTK, c'est le prix de l'économie : une sortie condensée convient à ls ou à un résumé de tests, elle devient dangereuse quand l'agent décide d'une action destructrice à partir d'elle. Les issues du dépôt montrent où ça casse :

• #2204, ouverte : le plafond passthrough_max_chars tronque silencieusement. Un git log base..HEAD sur 252 commits est revenu à environ 50 lignes, et l'agent a planifié une réécriture d'historique sur un périmètre faux. Le rapport date d'une version 0.x : le comportement exact en 1.0 reste à vérifier chez toi.
• #2121, ouverte : sur un git push réussi, le marqueur To <repo> est perdu. L'agent croit le push bloqué et le relance.
• #1313, ouverte : git status est plafonné en nombre de fichiers. Un agent peut stager dix fichiers sur vingt modifiés.
• #1714, fermée sans correctif prévu : faux positifs de réécriture sur make ou next build. À toi de vérifier tes commandes avec rtk hook check.

Mon incident de stash et de reset entre dans cette famille. Je ne l'ai pas reproduit et je n'en attribue pas la cause technique précise ; ce qui compte, c'est le scénario : une commande qui modifie l'état passe par une couche qui reformate la sortie, et l'agent ne voit plus la réalité. Les parades, de la plus fine à la plus large :

# Une commande sans filtre, mais tracée dans rtk gain
rtk bypass git stash list
rtk bypass git reset --hard HEAD~1

# Une commande avec le hook totalement désactivé
RTK_DISABLED=1 git rebase main

# Récupérer la sortie complète d'un filtre qui a signalé une élision
rtk recall <hash> --full

# ~/.config/rtk/config.toml : commandes jamais réécrites
[hooks]
exclude_commands = ["git stash", "git reset", "git rebase", "git cherry-pick", "git push", "git log", "docker exec"]
# Préfixe de sous-commande : "git push" n'exclut pas "git status". Préfixe ^ = regex.

Règle d'usage pour un agent : historique, stash, push et reset passent en rtk bypass ou en exclusion. Un comptage de commits se fait avec git rev-list --count, jamais en comptant les lignes d'un git log. Dans l'autre sens, une sortie condensée se prend comme complète tant qu'elle est exploitable ; on ne relance en bypass que si le résultat est inutilisable, vide alors qu'on attendait quelque chose ou contradictoire avec le code retour. Une consigne dans CLAUDE.md reste une demande que l'agent peut oublier : l'exclusion dans la configuration est la vraie garantie. Et garde en tête que git fsck --unreachable n'est un filet que tant que git gc n'est pas passé.

La licence BUSL de RTK 1.0 pose-t-elle problème à une entreprise ?

Depuis la 1.0, trois téléchargements coexistent. Le binaire par défaut rtk combine Apache-2.0 et BUSL-1.1, car il embarque le moteur de compression. L'édition rtk-oss est en Apache-2.0 seule, sans le moteur. Le démon rtk-proxy est en BUSL-1.1. La BUSL est une licence source-available, pas open source au sens de l'OSI. D'après le fichier engine/LICENSE, son Additional Use Grant autorise l'usage en production sans frais, mais interdit de proposer le moteur à des tiers comme produit ou service payant ou hébergé ; elle se convertit en Apache-2.0 le 9 septembre 2030.

• Usage interne par tes équipes de développement : couvert par le grant, sans redevance.
• Politique « licences OSI uniquement » ou redistribution dans une offre commerciale : installe rtk-oss (RTK_EDITION=oss avec le script d'installation, ou brew install rtk-ai/tap/rtk-oss). Les deux éditions installent le même binaire et ne coexistent pas.
• Ce que tu perds avec rtk-oss : les pipelines et la compression des sorties de Read et des outils MCP. Le hook de réécriture shell et tous les filtres de commandes restent identiques.
• Dans tous les cas, fais valider par ton service juridique : ceci n'est pas un avis juridique.

Côté télémétrie, la documentation la décrit comme désactivée par défaut et soumise à consentement lors de rtk init : un ping anonyme au plus une fois par jour, sans contenu de commande. Vérifie l'état réel de chaque poste avec rtk telemetry status, et coupe-la avec rtk telemetry disable ou RTK_TELEMETRY_DISABLED=1 si ta politique l'exige. Un hook qui réécrit des commandes exécutées relève de la même gouvernance que les extensions décrites dans l'article sur les Claude Code Mods.

Comment déployer RTK dans une équipe, et quand s’en passer ?

Le hook est une simple entrée de settings : il peut vivre dans le .claude/settings.json du dépôt ou dans la configuration utilisateur. La configuration de RTK, elle, est dans ~/.config/rtk/config.toml : versionne ce fichier avec ta liste d'exclusions et déploie-le par ton outil de provisioning. Épingle la version du binaire, le projet publie à un rythme très élevé. Et commence par un pilote d'une semaine sur deux ou trois développeurs, avec rtk gain --project, avant de généraliser.

• En CI et dans les scripts : tu veux des logs complets pour diagnostiquer, et une sortie filtrée n'est pas stable d'une version à l'autre.
• Pour les agents autonomes longs (refactorings de plusieurs heures, réécritures d'historique) : personne ne relit les sorties, et une troncature silencieuse devient une erreur de périmètre. Exclus les commandes git qui comptent, ou désactive le hook pour ces runs.
• Pour les sessions de release : stash, reset, rebase, push, déploiement passent en rtk bypass.
• Quand ta consommation vient d'ailleurs : si l'essentiel est le prompt système, l'historique et les lectures via Read, RTK ne change presque rien. Mesure d'abord.

RTK vaut l'installation, à condition de le traiter comme une optimisation à surveiller, pas comme une case cochée. Concrètement : installe-le sur un seul projet et vérifie la réécriture avec rtk hook check ; écris la liste d'exclusions git avant le premier incident, pas après ; mesure avec et sans sur une tâche réelle avant d'annoncer un chiffre ; lis la licence avant de déployer à l'équipe. Une économie de contexte reste une économie même quand elle est moindre que promise, mais elle ne vaut rien si l'agent décide sur une sortie déformée. Le prochain article de la série prend le problème par l'autre bout : ce qu'il faut mettre dans le contexte, et plus seulement ce qu'on peut en retirer.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours