Graphiques et schémas dans Claude Code : le mod charts

Claude Code répond en romans. Une comparaison entre trois options devient six paragraphes, une architecture devient un schéma ASCII décalé d’une colonne sur deux. J’en ai eu assez de lire ces pavés, alors j’ai écrit charts, un mod open source qui affiche des graphiques et des schémas dans Claude Code à la place du texte.

Claude écrit un bloc vega-lite, mermaid ou dot. Le mod le remplace par une image dans le terminal. Le premier rendu prend environ 280 ms, un graphique déjà dessiné revient en 60 ms. Et quand Claude pose une question avec AskUserQuestion, chaque option peut arriver avec son graphique ou son schéma.

Le problème : des réponses à lire au lieu de réponses à voir

Je pose souvent à Claude des questions dont la réponse est un chiffre ou une forme. “Le passage aux runners self-hosted a-t-il valu le coup ?” appelle quatre paires de durées. “Comment concevoir un système de webhooks avec retries ?” appelle un schéma de flux.

Sans aide, Claude répond avec du texte : des listes à puces de chiffres, un tableau, parfois un dessin ASCII. Le terminal de Claude Code rend le markdown, les tableaux et la coloration syntaxique, mais un bloc mermaid reste du code source. La demande existe côté Anthropic depuis décembre 2025 (issue #14375, toujours ouverte) : les schémas ASCII sont mal alignés et plats.

Le chiffre avant l’adjectif, c’est la règle de ce blog. Pour une comparaison, l’image avant le chiffre, c’est la règle que je voulais pour Claude.

Ce que fait le mod

charts est un mod, c’est-à-dire un plugin dont le code TypeScript s’accroche aux événements de Claude Code (documentation des mods). Il fait trois choses.

1. Il dessine les blocs. Tout bloc vega-lite devient un graphique, tout bloc mermaid ou dot devient un schéma. Les camemberts et les gantt Mermaid sont convertis en Vega-Lite pour partager le même thème. Dans le terminal, l’image est un PNG affiché par le protocole graphique de kitty. Dans l’application desktop, c’est un SVG.

2. Il pousse Claude à dessiner. Un mod qui sait dessiner ne sert à rien si Claude n’écrit jamais de bloc vega-lite. Le mod ajoute un guide au prompt système, détaillé plus bas.

3. Il remplace le dialogue d’AskUserQuestion quand les options portent des graphiques ou des schémas. La question s’affiche au-dessus du prompt, l’image à côté des options.

Le message stocké garde la source du bloc. Claude relit donc les données JSON, pas une image : aucun token de vision, aucune perte d’information quand la conversation continue.

Le guide qui fait dessiner Claude

C’est la partie qui m’a demandé le plus d’itérations. Le guide fait environ 3 000 caractères et dit à Claude quand dessiner, quoi dessiner, et surtout quoi ne plus écrire. Un extrait :

# Charts and diagrams by default
The person understands a picture faster than prose: show, then tell.
Do not wait to be asked for a chart or a diagram.

Add a vega-lite block, unprompted, whenever an answer holds any of:
two or more comparable quantities; a trend or anything over time;
a before/after; a distribution; a ranking.

Lead with the chart, then one or two sentences: the conclusion and the
one or two figures that matter. No table that repeats what the chart shows.

Use measured figures. When a value is an estimate, say so in the title
("estimation") and never present it as measured.

Trois règles changent tout. “Show, then tell” place l’image en tête de réponse. “No table that repeats what the chart shows” supprime le doublon que Claude ajoute par réflexe. “Estimation” dans le titre empêche Claude d’habiller une supposition en mesure, ce qui est le vrai risque d’un graphique : il a l’air plus sûr qu’une phrase.

Le guide interdit aussi les couleurs, les tailles et les thèmes dans les specs. Le mod applique les siens : un graphique écrit par Claude ressemble à tous les autres et tient dans la largeur du terminal. C’est la même logique que pour les skills Claude Code : une instruction courte et testée bat une instruction exhaustive.

AskUserQuestion avec des graphiques sur la même échelle

Quand Claude me fait choisir entre trois bases de données, chaque option a son aperçu. Trois graphiques séparés posent un problème : chacun calcule son propre axe y. Une barre haute dans l’option 1 et une barre haute dans l’option 3 ne veulent pas dire la même chose.

Le mod assemble les aperçus en une seule spec Vega-Lite hconcat et force les échelles partagées :

export function combinedSpec(items: readonly OptionChart[], totalWidth: number, totalHeight: number) {
  const perWidth = Math.max(60, Math.floor(totalWidth / Math.max(1, items.length)) - AXIS_ROOM)
  const perHeight = Math.max(40, totalHeight - CHROME)
  return {
    hconcat: items.map(({ index, label, spec }) => {
      const { $schema: _schema, config: _config, width: _w, height: _h, title: _t, ...rest } = spec
      return { ...rest, title: `${index}. ${label}`, width: perWidth, height: perHeight }
    }),
    resolve: { scale: { x: 'shared', y: 'shared', color: 'shared' } },
    spacing: 16,
  }
}

Une seule image, trois panneaux, un seul axe. Les barres redeviennent comparables d’un coup d’œil.

Quand les options sont des architectures et pas des chiffres, chaque option porte un schéma Mermaid. L’image suit l’option sous le curseur : flèche bas, le schéma change.

Comment ça marche

Le module de hooks tourne dans Claude Code, sans Node ni DOM. Vega et Graphviz ont besoin des deux. Le mod lance donc un petit script Node par image, le renderer, qui s’appuie sur Vega-Lite, beautiful-mermaid, Viz.js et resvg. Il écrit le PNG dans ~/.cache/claude-charts, avec le hash de la spec comme nom. Le terminal lit le fichier lui-même.

Le hook ui.render découpe chaque réponse en segments texte et graphique, dans l’ordre. Le texte repasse par le moteur de Claude Code pour garder la puce et le style. Les images sont rendues en parallèle, une par process. Un bloc invalide revient en source, avec l’erreur en dessous.

La partie la plus retorse est AskUserQuestion. Un hook dispose de 10 secondes de temps propre, et un humain met parfois plusieurs minutes à choisir. Un appel $.process.run en cours ne compte pas dans ce budget. Le hook lance donc un sh qui attend un fichier :

const WAITER = ['/bin/sh', '-c', 'while [ ! -f "$1" ]; do sleep 0.1; done; cat "$1"; rm -f "$1"', 'charts-ask']

La bande au-dessus du prompt écrit la réponse dans ce fichier, le sh sort, le hook rend le résultat à Claude. Si rien ne vient après 30 attentes de 10 minutes, le mod rend la main au dialogue d’origine. Échap ou Ctrl+C annulent proprement.

Les mesures

J’ai mesuré le renderer sur un Mac M4 Max avec Node 26 : 15 rendus par type, médiane de deux séries, une spec neuve pour le rendu à froid puis la même spec relue depuis le cache.

Un graphique déjà dessiné revient en 60 ms, à 15 ms du simple démarrage de Node : le cache disque répond sans charger Vega. Dans une même session, c’est encore mieux, le mod garde les 64 derniers rendus en mémoire et ne relance aucun process quand je remonte dans l’historique. Graphviz, compilé en WebAssembly, est assez rapide pour que le cache ne change rien.

Le projet compte environ 1 300 lignes de TypeScript pour les hooks, 420 lignes pour le renderer, et 95 tests (75 côté mod avec claude plugin test, 20 côté renderer).

Installation

Il faut Claude Code 2.1.280 ou plus, Node 20 dans le PATH, et pour les images dans le terminal un terminal compatible avec le protocole kitty, comme Ghostty ou kitty. Les autres terminaux affichent la description texte du graphique.

Les mods sont encore en accès anticipé. Claude Code ne les charge qu’avec cette variable dans ~/.claude/settings.json :

{
  "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" }
}

Puis :

claude plugin marketplace add https://gitlab.com/ThomasTartrau/charts.git
claude plugin install charts@tartrau-mods

Il n’y a rien à appeler. Une nouvelle session, une question avec des chiffres, et Claude dessine. La commande /charts règle le reste : on ou off, thème dark ou light, largeur et hauteur maximales en colonnes et en lignes, ratio des cellules du terminal. Les réglages sont gardés d’une session à l’autre.

Les alternatives

Je ne suis pas le seul à avoir eu l’idée. Deux plugins couvrent une partie du besoin :

• claude-mermaid dessine les blocs Mermaid avec beautiful-mermaid, la même bibliothèque que charts pour les schémas.
• claude-mermaid-terminal dessine Mermaid en art Unicode. Avantage réel : ça marche dans n’importe quel terminal, sans protocole d’image.

Les deux s’arrêtent aux schémas Mermaid. charts ajoute les graphiques de données Vega-Lite, Graphviz, les aperçus d’AskUserQuestion sur une échelle commune, et le guide qui fait dessiner Claude sans qu’on le demande. Si votre terminal n’affiche pas d’images et que seuls les schémas vous intéressent, l’art Unicode est le bon choix.

Ce que je changerais

Un process Node par image. 280 ms au premier rendu, c’est surtout le chargement de Vega. Un renderer qui reste en vie entre deux images supprimerait ce coût, au prix d’un process de plus à surveiller. Je ne l’ai pas fait parce que le cache couvre l’essentiel des redessins.

Le guide coûte des tokens. Environ 700 tokens par session, estimés à partir de ses 3 000 caractères. C’est le prix pour que Claude dessine sans qu’on le lui demande. Comme pour les skills, rien de ce qu’on ajoute au contexte n’est gratuit. /charts off le retire.

Une API encore mouvante. Les function hooks sont en accès anticipé et leur API peut changer d’une version de Claude Code à l’autre. Le moteur limite aussi ce qu’un mod peut faire : moins de 12 lignes autour du dialogue d’AskUserQuestion, et la bande au-dessus du prompt ne reçoit le clavier qu’après un Ctrl+X Tab ou un clic.

Le mod est sous licence MIT sur GitLab. Il fait partie de mon setup Claude Code, à côté de MCP RTK qui réduit les tokens des serveurs MCP.

Écrire ses propres mods, skills et hooks pour adapter Claude Code à sa façon de travailler, c’est l’un des sujets de ma formation Claude Code.