---
title: Terminal charts
description: Draw bar, line, area, scatter, sparkline, histogram, heatmap, pie, gauge and timeline charts in the terminal from a small YAML or JSON spec.
section: plugins
order: 120
audience: [user, builder, agent]
sources: [plugins/charts/README.md, plugins/charts/src, plugins/charts/AGENTS.md]
features: [plugins.charts]
---

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

````markdown
```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](/docs/plugins/themes.md)
- [Write a plugin](/docs/plugins/writing.md) (`registerBlockRenderer`)
