Skip to content
Docs menu

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.

View .md

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.