Chart Image Generator

Generate PNG chart images from data using Vega-Lite. Perfect for headless server environments.

Why This Skill?

Built for Fly.io / VPS / Docker deployments:

✅ No native compilation - Uses Sharp with prebuilt binaries (unlike canvas which requires build tools)
✅ No Puppeteer/browser - Pure Node.js, no Chrome download, no headless browser overhead
✅ Lightweight - ~15MB total dependencies vs 400MB+ for Puppeteer-based solutions
✅ Fast cold starts - No browser spinup delay, generates charts in <500ms
✅ Works offline - No external API calls (unlike QuickChart.io)

Setup (one-time)

cd /data/clawd/skills/chart-image/scripts && npm install

Quick Usage

node /data/clawd/skills/chart-image/scripts/chart.mjs \
  --type line \
  --data '[{"x":"10:00","y":25},{"x":"10:30","y":27},{"x":"11:00","y":31}]' \
  --title "Price Over Time" \
  --output chart.png

Chart Types

Line Chart (default)

node chart.mjs --type line --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output line.png

Quantitative X-domain clamp

Useful when you want a fixed numeric or temporal window without editing Vega-Lite by hand:

node chart.mjs --type line \
  --data '[{"minute":0,"value":12},{"minute":1,"value":18},{"minute":2,"value":14},{"minute":3,"value":20}]' \
  --x-field minute --y-field value --x-type quantitative \
  --x-domain 0,2 --title "First 3 Minutes" \
  --output x-domain.png

Bar Chart

node chart.mjs --type bar --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output bar.png

Area Chart

node chart.mjs --type area --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output area.png

Histogram

Use this for numeric distributions instead of pre-binned bar charts:

node chart.mjs --type histogram \
  --data '[{"value":12},{"value":18},{"value":19},{"value":24},{"value":31}]' \
  --x-field value --x-title "Response Time (ms)" --y-title "Count" \
  --bins 8 --tick-min-step-y 1 --x-label-angle -30 \
  --output hist.png

Pie / Donut Chart

# Pie
node chart.mjs --type pie --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output pie.png

# Donut (with hole)
node chart.mjs --type donut --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output donut.png

Candlestick Chart (OHLC)

node chart.mjs --type candlestick \
  --data '[{"x":"Mon","open":100,"high":110,"low":95,"close":105}]' \
  --open-field open --high-field high --low-field low --close-field close \
  --title "Stock Price" --output candle.png

Heatmap

node chart.mjs --type heatmap \
  --data '[{"x":"Mon","y":"Week1","value":5},{"x":"Tue","y":"Week1","value":8}]' \
  --color-value-field value --color-scheme viridis \
  --y-label-overlap greedy \
  --title "Activity Heatmap" --output heatmap.png

Multi-Series Line Chart

Compare multiple trends on one chart:

node chart.mjs --type line --series-field "market" \
  --data '[{"x":"Jan","y":10,"market":"A"},{"x":"Jan","y":15,"market":"B"}]' \
  --title "Comparison" --output multi.png

Stacked Bar Chart

node chart.mjs --type bar --stacked --color-field "category" \
  --data '[{"x":"Mon","y":10,"category":"Work"},{"x":"Mon","y":5,"category":"Personal"}]' \
  --title "Hours by Category" --output stacked.png

Volume Overlay (Dual Y-axis)

Price line with volume bars:

node chart.mjs --type line --volume-field volume \
  --data '[{"x":"10:00","y":100,"volume":5000},{"x":"11:00","y":105,"volume":3000}]' \
  --title "Price + Volume" --output volume.png

Sparkline (mini inline chart)

node chart.mjs --sparkline --data '[{"x":"1","y":10},{"x":"2","y":15}]' --output spark.png

Sparklines are 80x20 by default, transparent, no axes.

Options Reference

Basic Options

Option	Description	Default
`--type`	Chart type: line, bar, area, point, histogram, pie, donut, candlestick, heatmap	line
`--data`	JSON array of data points	-
`--output`	Output file path	chart.png
`--title`	Chart title	-
`--width`	Width in pixels	600
`--height`	Height in pixels	300

Axis Options

Option	Description	Default
`--x-field`	Field name for X axis	x
`--y-field`	Field name for Y axis	y
`--x-title`	X axis label	field name
`--y-title`	Y axis label	field name
`--x-type`	X axis type: ordinal, temporal, quantitative	ordinal
`--x-domain`	Clamp/zoom the X scale with `min,max` bounds for quantitative or temporal charts	auto
`--x-format`	Temporal X axis label format (d3-time-format, e.g. `%b %d`, `%H:%M`)	auto
`--x-sort`	X axis order: ascending, descending, or none (preserve input order)	auto
`--series-order CSV`	Explicit series/category order for multi-series and stacked legends (e.g. `Critical,High,Medium`)	data order
`--x-label-limit PX`	Max pixel width for X axis labels before Vega truncates them	auto
`--y-label-limit PX`	Max pixel width for Y axis labels before Vega truncates them	auto
`--x-ticks N`	Target X-axis tick count for dense or sparse charts	auto
`--y-ticks N`	Target primary/left Y-axis tick count for dense or sparse charts	auto
`--bins N`	Histogram bin count (`--type histogram` only)	Vega auto
`--tick-min-step N`	Minimum step between ticks on quantitative axes (great for counts / whole-number charts)	Vega auto
`--tick-min-step-x N`	Minimum step between ticks on quantitative X axes only	Vega auto
`--tick-min-step-y N`	Minimum step between ticks on quantitative Y axes only	Vega auto
`--x-label-angle N`	Rotate X-axis labels (for dense categories / timestamps)	-45
`--y-label-angle N`	Rotate Y-axis labels (useful for horizontal bars / heatmaps)	0 / Vega default
`--x-label-overlap MODE`	Force Vega X-axis overlap handling (`parity`, `greedy`, `true`, `false`) for crowded labels	Vega auto
`--y-label-overlap MODE`	Force Vega Y-axis overlap handling (`parity`, `greedy`, `true`, `false`) for crowded labels	Vega auto
`--y2-ticks N`	Target secondary/right Y-axis tick count for dual-axis and volume charts	auto
`--y-domain`	Y scale as "min,max"	auto
`--y-pad`	Add vertical padding as a fraction of range (e.g. `0.1` = 10%)	0

Visual Options

Option	Description	Default
`--color`	Line/bar color	#e63946
`--dark`	Dark mode theme	false
`--svg`	Output SVG instead of PNG	false
`--font-family`	CSS font-family string for chart text/legend/title theming	Helvetica, Arial, sans-serif
`--title-align`	Title alignment: `start`, `middle`, `end`	start
`--title-size N`	Title font size override in px	auto
`--subtitle-size N`	Subtitle font size override in px	auto
`--title-weight W`	Title font weight override (`normal`, `bold`, `100`-`900`)	auto
`--subtitle-weight W`	Subtitle font weight override (`normal`, `bold`, `100`-`900`)	auto
`--title-color`	Title text color override	theme text
`--subtitle-color`	Subtitle text color override	theme grid
`--grid-dash A,B`	Dash pattern for gridlines (for example `4,2`)	solid

Alert/Monitor Options

Option	Description	Default
`--show-change`	Show +/-% change annotation at last point	false
`--focus-change`	Zoom Y-axis to 2x data range	false
`--focus-recent N`	Show only last N data points	all
`--show-values`	Label min/max peak points	false
`--last-value`	Label the final data point value	false

Multi-Series/Stacked Options

Option	Description	Default
`--series-field`	Field for multi-series line charts	-
`--stacked`	Enable stacked bar mode	false
`--color-field`	Field for stack/color categories	-

Candlestick Options

Option	Description	Default
`--open-field`	OHLC open field	open
`--high-field`	OHLC high field	high
`--low-field`	OHLC low field	low
`--close-field`	OHLC close field	close

Pie/Donut Options

Option	Description	Default
`--category-field`	Field for pie slice categories	x
`--donut`	Render as donut (with center hole)	false

Heatmap Options

Option	Description	Default
`--color-value-field`	Field for heatmap intensity	value
`--y-category-field`	Y axis category field	y

Dual-Axis Options (General)

Option	Description	Default
`--y2-field`	Second Y axis field (independent right axis)	-
`--y2-title`	Title for second Y axis	field name
`--y2-color`	Color for second series	#60a5fa (dark) / #2563eb (light)
`--y2-type`	Chart type for second axis: line, bar, area	line
`--y2-format`	Right-axis format: percent, dollar, compact, integer, decimal4, or d3-format string	auto

Example: Revenue bars (left) + Churn area (right):

node chart.mjs \
  --data '[{"month":"Jan","revenue":12000,"churn":4.2},...]' \
  --x-field month --y-field revenue --type bar \
  --y2-field churn --y2-type area --y2-color "#60a5fa" --y2-format ".1f" \
  --y-title "Revenue ($)" --y2-title "Churn (%)" \
  --x-sort none --dark --title "Revenue vs Churn"

Volume Overlay Options (Candlestick)

Option	Description	Default
`--volume-field`	Field for volume bars (enables dual-axis)	-
`--volume-color`	Color for volume bars	#4a5568

Formatting Options

Option	Description	Default
`--y-format`	Y axis format: percent, dollar, compact, decimal4, integer, scientific, or d3-format string	auto
`--subtitle`	Subtitle text below chart title	-
`--hline`	Horizontal reference line: "value" or "value,color" or "value,color,label" (repeatable)	-

Annotation Options

Option	Description	Default
`--annotation`	Static text annotation	-
`--annotations`	JSON array of event markers	-

Alert-Style Chart (recommended for monitors)

node chart.mjs --type line --data '[...]' \
  --title "Iran Strike Odds (48h)" \
  --show-change --focus-change --show-values --dark \
  --output alert.png

For recent action only:

node chart.mjs --type line --data '[hourly data...]' \
  --focus-recent 4 --show-change --focus-change --dark \
  --output recent.png

Timeline Annotations

Mark events on the chart:

node chart.mjs --type line --data '[...]' \
  --annotations '[{"x":"14:00","label":"News broke"},{"x":"16:30","label":"Press conf"}]' \
  --output annotated.png

Temporal X-Axis

For proper time series with date gaps:

node chart.mjs --type line --x-type temporal \
  --data '[{"x":"2026-01-01","y":10},{"x":"2026-01-15","y":20}]' \
  --output temporal.png

Use --x-type temporal when X values are ISO dates and you want spacing to reflect actual time gaps (not evenly spaced).

Y-Axis Formatting

Format axis values for readability:

# Dollar amounts
node chart.mjs --data '[...]' --y-format dollar --output revenue.png
# → $1,234.56

# Percentages (values as decimals 0-1)
node chart.mjs --data '[...]' --y-format percent --output rates.png
# → 45.2%

# Compact large numbers
node chart.mjs --data '[...]' --y-format compact --output users.png
# → 1.2K, 3.4M

# Crypto prices (4 decimal places)
node chart.mjs --data '[...]' --y-format decimal4 --output molt.png
# → 0.0004

# Custom d3-format string
node chart.mjs --data '[...]' --y-format ',.3f' --output custom.png

Available shortcuts: percent, dollar/usd, compact, integer, decimal2, decimal4, scientific

Chart Subtitle

Add context below the title:

node chart.mjs --title "MOLT Price" --subtitle "20,668 MOLT held" --data '[...]' --output molt.png

--subtitle works across standard charts plus pie/donut, heatmap, candlestick, stacked, multi-series, volume-overlay, and dual-axis layouts.

Theme Selection

Use --dark for dark mode. Auto-select based on time:

Night (20:00-07:00 local): --dark
Day (07:00-20:00 local): light mode (default)

Social Size Presets

Use --output-size when the chart is meant for a specific surface:

# Bluesky / OG-style landscape post
node chart.mjs --type line --data '[...]' --output-size bluesky --output bluesky-chart.png

# Instagram / Threads portrait post
node chart.mjs --type line --data '[...]' --output-size portrait --output portrait-chart.png

Available presets include twitter, discord, slack, linkedin, bluesky (bsky alias), youtube, instagram, portrait, story, thumbnail, wide, and square.

Piping Data

echo '[{"x":"A","y":1},{"x":"B","y":2}]' | node chart.mjs --output out.png

Custom Vega-Lite Spec

For advanced charts:

node chart.mjs --spec my-spec.json --output custom.png

⚠️ IMPORTANT: Always Send the Image!

After generating a chart, always send it back to the user's channel. Don't just save to a file and describe it — the whole point is the visual.

# 1. Generate the chart
node chart.mjs --type line --data '...' --output /data/clawd/tmp/my-chart.png

# 2. Send it! Use message tool with filePath:
#    action=send, target=<channel_id>, filePath=/data/clawd/tmp/my-chart.png

Tips:

Save to /data/clawd/tmp/ (persistent) not /tmp/ (may get cleaned)
Use action=send with filePath — thread-reply does NOT support file attachments
Include a brief caption in the message text
Auto-use --dark between 20:00-07:00 Israel time

Updated: 2026-04-06 - added --y-label-angle for crowded categorical/heatmap charts and documented per-axis label rotation; version bumped to 2.6.33