Terminal charts
Draw bar, line, area, scatter, sparkline, histogram, heatmap, pie, gauge and timeline charts in the terminal from a small YAML or JSON spec.
The charts plugin (package @venom/charts, built into the CLI) draws charts in Unicode block elements and braille, or plain ASCII where the terminal has no UTF-8. It has no dependencies and makes no network calls. A drawn chart is display only: it never enters the model's context.
What it adds
| Part | What |
|---|---|
```chart blocks |
a fenced chart block in an assistant message is drawn in the TUI at the message's width. The session keeps the spec text, so the prompt cache, /copy and jsonl export see the spec. A bad spec shows one line, ⚠ chart: <problem> |
the chart tool |
chart({ spec, path? }) draws for the user and returns one summary line to the model. path is a CSV, TSV or JSON file read through the read tool, so read permission rules and hooks apply. Read-only |
/chart |
/chart results.csv [type], /chart data.json, /chart spec.yaml, or an inline spec (/chart type: bar data: {a: 1, b: 2}); a notification, nothing reaches the model |
the charts skill |
the spec reference, read by the model when it wants a chart |
| exports | /export and venom export draw the blocks as text in html and md; jsonl keeps the spec |
Per-request cost: about 126 tokens of tool schema and 17 of skill listing, both in the cached prefix.
Example
```chart
type: line
title: p50 latency
unit: ms
x: [2026-10-05, 2026-10-06, 2026-10-07]
series: { model-a: [912, 870, 940], model-b: [1610, 1480, 1555] }
```Spec reference
YAML or JSON. Only data, series or from is required; the type is inferred when left out (dates or many numeric x values give a line, a matrix a heatmap, tasks a gantt, otherwise bars).
| Type (aliases) | Draws |
|---|---|
bar (hbar, bars) |
horizontal bars at eighth-block precision; negatives left of zero; grouped or stacked: true |
column (vbar, columns) |
vertical bars; falls back to bar when they do not fit |
line, area |
braille lines, several series; area fills to zero |
scatter (points) |
braille dots |
spark (sparkline) |
one line per series with min, max and last value |
hist (histogram) |
bins (Sturges' count by default, bins: n) |
heatmap (heat, matrix) |
a shade ramp per cell with a key |
pie (donut, share) |
a proportional bar with a legend (terminal cells are too coarse for slices) |
gauge (progress, meter) |
one bar per value against max (default 100), coloured at thresholds (default [0.7, 0.9]) |
gantt (timeline, trace) |
one bar per task from start to end |
| Data form | Meaning |
|---|---|
data: { label: value } |
one series |
data: [3, 1, 4] |
values, labels 1 to n |
data: [[x, y], …] |
pairs |
data: [{…}, …] |
rows; keys are columns |
data: | then CSV or TSV |
first column labels or x, other numeric columns series |
x: […] with series: { name: […] } |
several series over x |
from: table |
the Markdown table right above the block |
matrix, rows, cols |
heatmap |
data: [{ name, start, end | duration, group }] |
gantt |
Numbers may be written 1,234, $5, 12%, 3.2k; an empty cell, -, null or NaN is a gap. All-ISO-date x values make a UTC time axis.
Options: title, unit (currency signs go before the number), log: true, stacked: true, values: false, height (2 to 60, default 10), width, min, max, bins, x_label, y_label, points: true, thresholds, legend. At most 20,000 values per chart. Series colours come from the theme's chart.1 to chart.6.
For builders
@venom/charts/lib is the rendering library alone (scales, bars, braille plots, text widths, palettes), with no pi dependency. createChartsExtension and parseChartSpec come from the package root. Output is deterministic and every line fits the width asked for.
Related
- Themes
- Write a plugin (
registerBlockRenderer)