# Optimiser le fichier de configuration TOML de RTK-AI pour un projet Next.js 16.x (App Router) ## TL;DR - **RTK-AI = « Rust Token Killer »**, un proxy CLI qui compresse la sortie des commandes avant qu'elle n'atteigne le LLM de votre agent (Claude Code, Cursor, etc.). Son `config.toml` ne configure **pas** le runtime/build de Next.js. « Vitesse de lecture » et « vitesse d'exécution » doivent donc se comprendre au sens de RTK : rapidité du filtrage des commandes de lecture de fichiers (`read`, `ls`, `find`, `grep`) et overhead du proxy lui-même (annoncé < 10 ms par commande dans le README officiel). - Les vrais leviers TOML qui accélèrent la lecture/le parsing et l'exécution sont : `[filters].ignore_dirs`/`ignore_files` (élargir aux dossiers Next.js comme `.next`, `.turbo`, `.vercel`), la section `[limits]` (plafonner `grep_max_results`, `passthrough_max_chars`…), `[tee] mode="failures"` (ne jamais passer à `"always"`), et `[tracking]` (chemin SQLite + rétention). Le niveau de filtrage de `rtk read` (`-l aggressive`) reste un **flag CLI**, pas une clé de config. - Plusieurs « optimisations » qu'on pourrait imaginer **n'existent pas** : pas de clé pour régler la vitesse de parsing, pas de profil global de compression (`--profile` est une demande ouverte, #488), pas de cache de fichiers. Attention aussi à des bugs connus (`telemetry.enabled=false` ignoré #1134, `exclude_commands` non câblé sur le hook #1335, `rtk ls` → `(empty)` #1418) et à la portée du hook (Bash uniquement ; les outils Read/Grep/Glob natifs de l'agent ne passent pas par RTK). ## Key Findings 1. **RTK n'est pas un outil Next.js.** C'est un binaire Rust unique (≈ 4 Mo, codebase à ~92,3 % de Rust, zéro dépendance) qui s'intercale entre l'agent IA et les outils CLI. La page d'accueil officielle revendique « **89% noise reduction measured across 2,900+ real-world dev commands: cargo test 91.8%, git status 80.8%, find 78.3%, grep 49.5%** » ; le README annonce « **100+ supported commands, <10ms overhead** ». Sur une session Claude Code de 30 min (projet TypeScript/Rust moyen), le tableau de benchmark du README fait passer le total de **~118 000 à ~23 900 tokens (−80 %)**. 2. **La config par défaut documentée** (`rtk config --create`) comprend `[tracking]`, `[display]`, `[filters]`, `[tee]`, `[telemetry]`, `[hooks]`. La sortie réelle de `rtk config` (issue #1134) révèle en plus une section **`[limits]`** non documentée et la clé **`tee.max_file_size`**. 3. **Pour « accélérer la lecture/le parsing »**, le levier principal est `[filters]` : tout chemin listé dans `ignore_dirs`/`ignore_files` est exclu du parcours et du parsing des commandes de fichiers (`ls`, `find`, `grep`, `cat`/`rtk read`). Y ajouter les dossiers spécifiques à Next.js (`.next`, `.turbo`, `.vercel`, `out`, `coverage`) réduit le travail d'I/O et de filtrage **et** la taille de sortie. 4. **Pour « accélérer l'exécution / le runtime du proxy »**, les leviers sont la section `[limits]` (plafonds de traitement), `[tee]` (éviter l'écriture disque systématique), `[tracking]` (overhead SQLite) et `[display]` (moins de formatage). 5. **Le niveau de filtrage de lecture** (`None` / `Minimal` / `Aggressive`) se choisit via le flag `rtk read -l aggressive` ; il n'existe **aucune clé `config.toml`** pour fixer un niveau par défaut (feature request ouverte #488). 6. **Bugs et limites à connaître** : portée Bash uniquement ; `telemetry.enabled` ignoré dans le fichier (#1134) ; `exclude_commands` non honoré sur le chemin de réécriture du hook en 0.36.0 (#1335, #243) ; corruption silencieuse en cas de redirection/pipe (#1282) ; `rtk ls` renvoyant `(empty)` en 0.37.1 (#1418). ## Details ### Ce que contrôle réellement le fichier `config.toml` Emplacement : `~/.config/rtk/config.toml` (Linux) ou `~/Library/Application Support/rtk/config.toml` (macOS). Le fichier est optionnel ; en son absence RTK applique des valeurs par défaut codées en dur. La priorité est : variables d'environnement > `config.toml` > défauts. Le fichier n'est pas créé automatiquement : `rtk config --create`. Configuration par défaut complète (telle qu'affichée par `rtk config`, issue #1134) : ```toml [tracking] enabled = true history_days = 90 [display] colors = true emoji = true max_width = 120 [filters] ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor"] ignore_files = ["*.lock", "*.min.js", "*.min.css"] [tee] enabled = true mode = "failures" max_files = 20 max_file_size = 1048576 [telemetry] enabled = true [hooks] exclude_commands = [] [limits] grep_max_results = 200 grep_max_per_file = 25 status_max_files = 15 status_max_untracked = 10 passthrough_max_chars = 2000 ``` ### Levier 1 — `[filters]` : accélérer la lecture (parsing/parcours) ET réduire les tokens `ignore_dirs`/`ignore_files` s'appliquent aux commandes de lecture de fichiers (`ls`, `find`, `grep`, `cat`/`rtk read`). `rtk find` utilise le crate `ignore` (`WalkBuilder`) et respecte déjà `.gitignore`, mais étendre explicitement la liste aux artefacts Next.js évite de parcourir et de parser des dizaines de milliers de fichiers générés. Configuration recommandée pour Next.js 16 / App Router : ```toml [filters] ignore_dirs = [ ".git", "node_modules", "target", "__pycache__", ".venv", "vendor", ".next", # sortie de build Next.js (très volumineuse) ".turbo", # cache Turbopack/Turborepo ".vercel", # artefacts de déploiement Vercel "out", # export statique (next export) "build", "dist", # sorties de build génériques "coverage", # rapports de tests ".swc", # cache du compilateur SWC ] ignore_files = [ "*.lock", "*.min.js", "*.min.css", "*.tsbuildinfo", # cache incrémental TypeScript "next-env.d.ts", # fichier généré, sans valeur pour le LLM "*.map", # source maps ] ``` **Effet sur la vitesse de lecture** : moins de fichiers parcourus → traversal plus rapide, moins de contenu parsé par les filtres, et sortie plus compacte (donc moins de tokens). C'est le gain « read » le plus direct et le plus sûr pour un projet Next.js, dont le dossier `.next` à lui seul peut contenir des dizaines de milliers de fichiers générés. ### Levier 2 — `[limits]` : accélérer l'exécution et borner le parsing Cette section (présente dans le binaire — `src/core/config.rs` lignes ~101-112 selon DeepWiki — mais absente de la doc officielle) définit des seuils anti-débordement appliqués au runtime. Réduire ces plafonds limite le travail de filtrage sur les grosses sorties et la quantité de texte traitée : ```toml [limits] grep_max_results = 120 # défaut 200 — moins de résultats à formater/émettre grep_max_per_file = 20 # défaut 25 status_max_files = 15 # défaut 15 (inchangé) status_max_untracked = 10 # défaut 10 (inchangé) passthrough_max_chars = 2000 # défaut 2000 — borne la sortie des commandes non filtrées ``` **Attention (compromis correctness)** : ces plafonds tronquent réellement la sortie (issue #1313 : un `grep` peut être silencieusement coupé à 200/25). Les baisser accélère et économise des tokens, mais l'agent peut manquer des occurrences. Pour un gros monorepo headless commerce, garder `grep_max_results` assez haut sur les recherches d'audit, ou utiliser `rtk grep "motif" -- -A 2` ponctuellement. La section `[limits]` est apparue dans une version postérieure à mi-mars 2026 ; vérifiez sa présence avec `rtk config`. ### Levier 3 — `[tee]` : éviter l'I/O disque inutile Le système « tee » sauvegarde la sortie brute complète sur disque quand une commande échoue, et ajoute le chemin du log à la sortie filtrée (les sorties < 500 octets sont ignorées, le plafond par fichier est 1 Mo). **Garder `mode = "failures"`** (défaut). Passer à `"always"` écrirait chaque sortie sur disque → I/O et latence ajoutées à chaque commande. Réglages : ```toml [tee] enabled = true mode = "failures" # NE PAS mettre "always" (coût I/O) ; "never" si vous acceptez de perdre le filet de sécurité max_files = 10 # rotation plus agressive (défaut 20) max_file_size = 1048576 # 1 Mo (plafond ; au-delà, troncature) ``` Variable d'environnement utile : `RTK_TEE_DIR` pour pointer le répertoire tee vers un disque rapide / tmpfs. `RTK_TEE=0` désactive le tee pour une session. ### Levier 4 — `[tracking]` : réduire l'overhead SQLite Chaque commande proxifiée écrit dans une base SQLite (`~/.local/share/rtk/history.db`) via `rusqlite`, avec un nettoyage déclenché à chaque écriture (`DELETE FROM commands WHERE timestamp < date('now','-90 days')`, rétention 90 j par défaut, configurable via `history_days`). Pour réduire l'overhead d'exécution : ```toml [tracking] enabled = true # mettre false supprime tout l'overhead d'écriture, mais on perd `rtk gain` history_days = 30 # rétention plus courte = base plus petite, nettoyage plus léger # database_path = "/chemin/rapide/history.db" # placer la base sur SSD/tmpfs ``` `RTK_DB_PATH` permet de surcharger le chemin par session. Mettre `enabled = false` élimine l'écriture mais désactive l'analytique `rtk gain`/`rtk discover`. ### Levier 5 — `[display]` : moins de formatage, sortie plus propre pour le LLM ```toml [display] colors = false # supprime les codes ANSI (inutiles, voire nuisibles, pour un LLM) emoji = false # supprime les emojis décoratifs max_width = 100 # largeur de sortie plus étroite ``` Désactiver `colors`/`emoji` réduit légèrement le travail de formatage et produit une sortie plus dense pour le modèle. ### Levier 6 — `[hooks].exclude_commands` : éviter de réécrire ce qui n'y gagne rien ```toml [hooks] exclude_commands = ["playwright", "next dev", "vercel"] ``` Exclut de la réécriture les commandes interactives/longues (serveur de dev, déploiement) où le filtrage n'apporte rien ou casse le flux. **Bug à connaître (#1335, #243)** : en 0.36.0, `exclude_commands` est lu par le chemin du hook mais **non câblé** sur `rtk rewrite` ; vérifiez le comportement sur votre version. Solution de repli : `RTK_DISABLED=1 ` pour un contournement ponctuel. Les motifs s'appliquent après suppression des préfixes d'environnement (`sudo`, `VAR=val`) et acceptent les sous-commandes (`"git push"`) ou la regex (préfixe `^`). ### Filtres spécifiques au projet : `.rtk/filters.toml` Pour des filtres versionnés et partagés en équipe (façon `.eslintrc`), créez `.rtk/filters.toml` à la racine du repo. Ordre de résolution : `.rtk/filters.toml` (projet) → `~/.config/rtk/filters.toml` (global) → filtres TOML intégrés → passthrough (premier match gagne). Primitives du DSL (pipeline en 8 étapes) : `strip_ansi`, `replace`, `match_output`, `strip_lines_matching`, `keep_lines_matching`, `truncate_lines_at`, `max_lines`, `head_lines`, `tail_lines`, `on_empty`. Exemple pour réduire le bruit d'une commande de lint maison : ```toml [filters.next-lint] description = "Compacter la sortie de next lint" match_command = "^next\\s+lint\\b" strip_ansi = true strip_lines_matching = ["^\\s*$", "^info -", "^\\s*✓"] max_lines = 80 on_empty = "✓ lint clean" ``` **Limite importante (#821, #820)** : un filtre TOML utilisateur **ne peut pas** surcharger une commande déjà gérée nativement par RTK (ex. `next build`, `tsc`, `eslint` via `rtk lint` sont routés par Clap avant le moteur TOML). Et `rtk rewrite` ne consulte pas les filtres TOML utilisateurs, donc le hook ne réécrira pas automatiquement vos commandes custom. ### Le filtrage de lecture de fichiers : ce qui existe vraiment `rtk read` applique un filtrage selon un `FilterLevel` : `None` (brut), `Minimal` (retire commentaires, lignes vides, imports redondants), `Aggressive` (ne garde que les signatures de fonctions/classes — détection de langage par extension, JS/TS pris en charge). Cela se pilote par **flag CLI** (`rtk read fichier.tsx -l aggressive`), pas par config. Le module de lecture traite ligne par ligne (streaming, I/O synchrone, compilation regex paresseuse), d'où l'overhead < 10 ms. Limites notables : `rtk read` ne supporte pas la lecture d'une **plage de lignes** (#1104), et `rtk ls` renvoie `(empty)` en 0.37.1 (#1418). Pour la navigation de code Next.js, `rtk read -l aggressive` sur les gros composants/route handlers donne au modèle les signatures sans les corps (≈ −95 % sur un fichier de 500 lignes), et `rtk smart fichier.tsx` produit un résumé heuristique de 2 lignes. ### Portée et contexte Next.js 16 Next.js 16 utilise Turbopack par défaut pour `next dev` et `next build`, App Router par défaut. RTK dispose d'un filtre `next build` (≈ −80 %, garde le résumé des routes + erreurs), `rtk tsc` (erreurs TS groupées par fichier), `rtk lint`/eslint (≈ −84 %, groupé par règle), `rtk vitest`/`rtk playwright test` (échecs uniquement), `rtk prisma`. **Point crucial** : le hook ne réécrit que les appels **Bash** ; les outils natifs Read/Grep/Glob de l'agent ne passent pas par RTK. Pour en bénéficier, il faut lancer des commandes shell (`cat`/`head`/`tail`, `rg`/`grep`, `find`) ou appeler explicitement `rtk read`/`rtk grep`/`rtk find`. ## Recommendations **Étape 1 — Le `config.toml` recommandé (gains immédiats, sans risque).** Créez/éditez `~/.config/rtk/config.toml` : ```toml [tracking] enabled = true history_days = 30 [display] colors = false emoji = false max_width = 100 [filters] ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor", ".next", ".turbo", ".vercel", "out", "build", "dist", "coverage", ".swc"] ignore_files = ["*.lock", "*.min.js", "*.min.css", "*.tsbuildinfo", "next-env.d.ts", "*.map"] [tee] enabled = true mode = "failures" max_files = 10 max_file_size = 1048576 [telemetry] enabled = false [hooks] exclude_commands = ["next dev", "playwright"] [limits] grep_max_results = 150 grep_max_per_file = 20 status_max_files = 15 status_max_untracked = 10 passthrough_max_chars = 2000 ``` > ⚠️ Incluez toujours `history_days` sous `[tracking]` : un `[tracking]` partiel (ex. juste `enabled = false`) fait échouer le parsing (champ `history_days` manquant, #1134). **Étape 2 — Désactiver la télémétrie de façon fiable.** Comme `telemetry.enabled = false` dans le fichier est ignoré (#1134), utilisez `export RTK_TELEMETRY_DISABLED=1` (dans votre `.zshrc`/`.bashrc`) **ou** `rtk telemetry disable`. (À noter : la télémétrie est de toute façon opt-in/désactivée par défaut dans les versions récentes.) **Étape 3 — Mesurer.** Lancez `rtk gain` (et `rtk gain --history`) avant/après pour quantifier les tokens économisés, et `rtk discover` pour repérer les commandes lancées sans RTK. Vérifiez l'overhead avec `hyperfine 'rtk grep "motif" .' --warmup 3` (doit rester < 10 ms hors temps de la commande sous-jacente). **Étape 4 — Filtres projet.** Si l'équipe a des scripts maison verbeux (seed, codegen, scripts de migration), ajoutez un `.rtk/filters.toml` versionné. Ne tentez pas d'y surcharger `next build`/`tsc`/`eslint` (routés nativement, #821). **Seuils qui changeraient ces recommandations** : si l'agent manque des résultats de recherche → remontez `grep_max_results`/`grep_max_per_file`. Si vous perdez des erreurs de build → passez `tee.mode = "always"` temporairement le temps d'un debug. Si l'overhead disque pose problème en CI → `RTK_TEE_DIR` vers tmpfs ou `tracking.enabled = false`. ## Caveats - **RTK ne touche ni au build ni au runtime de Next.js.** Aucune clé du `config.toml` n'accélère le rendu, le bundling Turbopack ou le démarrage du serveur. Les gains sont sur la consommation de tokens et l'overhead du proxy. - **Pas de réglage de « vitesse de parsing » ni de profil global.** Le niveau de filtrage de lecture est un flag CLI (`-l`), et la demande de profils configurables (`--profile heavy/normal/...`) reste ouverte (#488). - **Portée Bash uniquement.** Si l'agent s'appuie sur ses outils natifs Read/Grep/Glob, RTK ne filtre rien. - **Bugs « config présente, câblage absent ».** `telemetry.enabled` (#1134) et `exclude_commands` côté hook (#1335) peuvent être ignorés selon la version ; `rtk ls` → `(empty)` en 0.37.1 (#1418) ; corruption silencieuse en pipe/redirection (#1282). - **Compromis de troncature.** Baisser `[limits]` accélère mais peut masquer des informations (résultats grep, fichiers modifiés). À calibrer selon la taille du projet. - **Divergence de licence dans les sources.** La FAQ de rtk-ai.app indique « **open source under the MIT license** », tandis que le footer du README et certaines pages citent « **Apache License 2.0** » — à vérifier directement dans le fichier `LICENSE` du dépôt si ce point est important pour vous. - **Versions.** Le README épingle l'exemple en 0.28.2, DeepWiki documente la 0.40.0, et le projet évolue très vite (≈ 0.42.0 en mai 2026 ; le dépôt affiche déjà ~58 k étoiles). La section `[limits]` et `tee.max_file_size` sont apparues après mi-mars 2026 ; vérifiez votre version avec `rtk --version` et inspectez votre config réelle avec `rtk config` avant d'appliquer ces réglages.