Skip to content
plotagents · protocol 0.12.0MIT · zero dependencies · SVG

Charts are a language. Now AI speaks it.

plotagents is an open protocol between a model and the page. The model says what a chart means: the data, the finding, the unit. The library answers with a finished, accessible chart, or with the exact fix it needs.

Live · a model draws by calling plotagents
Person

Here’s our rollout plan. Where are we, and what could slip?

Model → tool call
plot({  type: "gantt",  title: "Go-live is June 15, and the ERP integration is the critical path",  subtitle: "Rollout plan by phase, 2026. The filled part of each bar is progress",  source: "illustrative data",  data: /* 10 tasks: phase, task, start, end, progress, after */,  task: "task", start: "start", end: "end", group: "phase",  progress: "progress", dependsOn: "after",  today: "2026-03-12", dashed: "tentative",  dashedLabel: "To be confirmed", locale: "en",})
plotagents → model
{  ok: true, type: "gantt",  svg: "<svg …>…</svg>",  // 13.1 kB, with aria-label and <desc>  description: "Gantt chart of 10 tasks in 4 phases, from Jan 5, 2026 to Jun 15, 2026. Longest: ERP integration (46 days). Milestones: Findings report (Feb 9),…",  errors: [], warnings: [], suggestions: []}
Gantt chart of 10 tasks in 4 phases, from Jan 5, 2026 to Jun 15, 2026. Longest: ERP integration (46 days). Milestones: Findings report (Feb 9), Go-live (Jun 15). Overall progress: 35%.Go-live is June 15, and the ERP integration is thecritical pathRollout plan by phase, 2026. The filled part of each bar is progressTo be confirmedFeb 2026MayJunUser interviewsProcess mapFindings reportData modelAgent prototypeERP integrationKPI dashboardUser testingTrainingGo-liveDiscovery· 3Design· 2Build· 3Launch· 2100%100%Feb 980%45%10%0%0%Jun 15Today · Mar 12Source: illustrative data
Agent SkillClaude · Cursor · Codex · any AI

Install it once. Your AI charts with plotagents from then on.

The skill tells your assistant to use plotagents for every chart, map, table and dashboard. It carries the essentials of the protocol and checks npm for a newer release before it starts, so it never falls behind.

Install the skillplotagents-skill.zip · for the Claude app $ npx skills add carlosnavarreteliz/plotagents
  1. Claude Code, Cursor, Codex… Run the command above in your terminal.
  2. Claude app Download the .zip and upload it in Settings → Capabilities → Skills.
  3. Any other AI Paste SKILL.md into its instructions.
01 · The protocolsafePlot(spec) → { ok, svg, description, errors, warnings, suggestions }

One message each way. No pixels.

A model is good at knowing what the data says and bad at placing tick labels. So the protocol asks only for meaning, and keeps the craft on this side of the wire.

01

Say

The model describes the chart, not the drawing: rows of data, the role of each field, and a title that states the finding.

02

Check

safePlot never throws. It validates against the JSON Schema and the design rules before anything is drawn.

03

Repair

Every issue carries a fix written for a model to read. It applies the fix and calls again, usually once.

04

Show

An SVG comes back with its alt text in description, so the model can read what it drew before it answers.

First call

plot({
  type: "donut",
  data: /* 11 rows: city, stores */,
  label: "city",
  value: "store_count",
  locale: "en",
})

A wrong field name and an 11-slice donut: two classic mistakes.

plotagents answers

{
  ok: false, svg: null,
  errors: [
    { message: "The field \"store_count\" (value) does not exist.",
      fix: "Available fields: city, stores" }
  ],
  warnings: [
    { message: "11 slices: beyond 6 a donut cannot be read; the rest fold into \"Other\".",
      fix: "Use `type: \"bar\"` or `type: \"treemap\"`." }
  ],
  suggestions: [  ]
}

Second call → chart

Bar chart of Stores across 11 categories. Highest: Santiago with 430 (51%). Lowest: Puerto Montt with 18.Santiago has more stores than the next ten citiescombined: 430 vs 413Stores by city, 2025Santiago430Valparaíso96Concepción88La Serena41Antofagasta39Temuco35Rancagua30Talca26Arica21Iquique19Puerto Montt18Source: illustrative data
02 · The vocabulary44 chart types · schema.json

A small grammar for every chart.

Ten words carry most charts. Name a type, or leave it out and plotagents infers it from the data. seaborn names work too.

title
The finding, as a sentence with the number.
subtitle
How to read it: measure, unit, period.
source
Where the data comes from. Always.
data
Rows, as they come: [{ region, sales }].
x · y · series
Which field plays which role.
highlight
The one thing the reader should see.
dashed
What is not a firm number yet.
facet · time
Small multiples; one period at a time.
geo
Chile, the US, the world, or your own GeoJSON.
locale
"en" or "es", for numbers and dates.

bar/ line/ area/ scatter/ treemap/ sunburst/ donut/ pie/ heatmap/ sankey/ kpi/ hist/ kde/ ecdf/ regplot/ jointplot/ box/ violin/ strip/ swarm/ point/ radar/ network/ chord/ pyramid/ flowchart/ gantt/ wordcloud/ choropleth/ symbolmap/ pointmap/ table/ corr/ pairplot/ spark/ bump/ waffle/ dendrogram/ dotplot/ rail

Plus barplot, histplot, violinplot, lmplot… and plain words like timeline, map or roadmap. The full contract is one file: schema.json.

04 · MapsGeoJSON · TopoJSON · URL

Bring your own geometry.

Chile, the United States and the world come built in. Anything else is one field away: comunas, school districts, sales territories, a campus, a floor plan.

  • Any shape in geo. A FeatureCollection, a Feature, a list of features, a TopoJSON, or a URL in the browser.
  • No key to configure. The property that matches your rows (NOM_COM, GEOID, ADMIN) is found for you.
  • Layers on top. markers by longitude and latitude, layers for rivers, routes or borders.
  • Your framing. fitTo zooms to a few regions or a box; projections from Mercator to UTM metres.
  • Text values work. A party or a language colors by category, with a legend.
plot({
  type: 'choropleth',
  geo: myGeoJSON,     // or TopoJSON, or a URL
  data, key: 'country', value: 'language',
  markers: { data: capitals, label: 'city' },
  layers: [{ geo: tropic, dash: true }],
  fitTo: ['Chile', 'Argentina'],  // optional
})
Choropleth map of Language across 12 areas: Spanish (9), Portuguese (1), English (1), Dutch (1). 12 markers (Capital). Layers: Tropic of Capricorn.Spanish is an official language in 9 of the 12 SouthAmerican countriesMain official language by country, with capitalsSpanishPortugueseEnglishDutchTropic of CapricornCapitalBuenos AiresSantiagoLimaBogotáBrasíliaCaracasQuitoLa PazAsunciónMontevideoParamariboVenezuelaSpanishGuyanaEnglishSurinameDutchColombiaSpanishEcuadorSpanishPeruSpanishBrazilPortugueseBoliviaSpanishParaguaySpanishUruguaySpanishArgentinaSpanishChileSpanishSource: Natural Earth (public domain)
05 · The craftFrom Wilke’s Fundamentals of Data Visualization and newsroom practice

Rules the model can’t break.

Agents reach for dual axes, twelve-slice pies and titles that say nothing. Here, the good decision is the only one available.

01

The title states the finding

A full sentence with the key number. lint flags titles that only name the chart; describe writes the alt text.

02

One axis, always

No dual axes: they invent correlations. index: true rebases to 100, facet draws panels on a shared scale.

03

Labels where the eye is

Lines are labeled at their ends, values sit on the bars, colliding labels get leader lines. A legend only when it is needed.

04

Color follows the entity

Eight colorblind-safe colors in a fixed order. “Copper” keeps its color when you filter, drill down or move the slider.

05

Honest about uncertainty

Estimates and projections are hatched with dashed, never a new color, and the legend says what the hatching means.

06

Fast, accessible SVG

Zero dependencies, server-side rendering, an aria-label and a <desc> in every chart, and dense data batched into paths.

06 · IntegrateAnthropic · OpenAI · any runtime

Hand it to any model.

The protocol ships as a JSON Schema and a ready-made tool definition, plus a one-page guide for the system prompt and an Agent Skill.

  • The Agent Skill makes Claude, Cursor or Codex reach for plotagents on their own.
  • toolDefinition() turns the schema into a tool for Claude or OpenAI.
  • safePlot(spec) returns the SVG or the errors, each with a fix.
  • describe(spec) writes alt text the model can check.
  • The guide for agents, also as AGENTS.md and llms.txt.
  • render() in the browser adds tooltips, drill-down, map zoom, and time controls when the spec asks for them.
import Anthropic from '@anthropic-ai/sdk';
import { safePlot, toolDefinition } from 'plotagents';

const client = new Anthropic();
const res = await client.messages.create({
  model: process.env.ANTHROPIC_MODEL,
  max_tokens: 4096,
  tools: [toolDefinition()],        // the whole protocol, as JSON Schema
  messages: [{ role: 'user', content: 'Chart service times per clinic: …' }],
});

const call = res.content.find((b) => b.type === 'tool_use');
const { ok, svg, description, errors } = safePlot(call.input);
// Never throws. If !ok, return `errors` as the tool result:
// each one carries a `fix`, and the model calls again.

Ask for a dashboard. Get a good one.

The same idea, one level up: the model lists KPIs, charts and filters; dashboard() lays them out the way an analyst would, and filters work across every panel.

  • Numbers first. Up to five KPIs, computed from the data, with year-over-year change and a sparkline.
  • Z-pattern. The trend goes full width; the rest fills balanced rows of a 12-column grid.
  • One color per entity across every chart, one theme, one source line.
  • Filters as buttons that move every chart and KPI at once.
  • One HTML file. Works offline, prints, and turns into a PDF.
dashboard({
  title: 'How are southern sales doing?',
  data: sales,
  kpis: [{ label: 'Sales 2025', field: 'sales', agg: 'sum',
           compare: { field: 'year', current: 2025, previous: 2024 } }],
  charts: [trend, map, byChannel, treemap],
  filters: ['region', 'channel'],
})

Let your agent show, not just tell.

Install the AI skill $ npm install plotagents Get started → Star on GitHub