Glyph Arts

Glyph Arts Skill

Vision

When AI answers in chat, useful visuals should be able to live there too. Chat output comes first. Terminal rendering, files, and host previews are exits for cases where the drawing needs more room, persistence, or human review. glyph-arts gives the AI a native visual language without forcing every drawing through a GUI.

Invocation

SKILL=~/.claude/skills/glyph-arts
python $SKILL/scripts/chart.py <type> [--json '<data>'] [--file path.json] \
  [--duckdb 'SQL'] [--db PATH] \
  [--title 'T'] [--width N] [--height 20] [--theme pro] \
  [--sample N] [--xlabel X] [--ylabel Y] \
  [--xlim MIN MAX] [--ylim MIN MAX] \
  [--xscale linear|log] [--yscale linear|log] \
  [--orientation vertical|horizontal] [--output FILE] [--no-color] \
  [--link-data URL] [--link-title URL] [--statusline]

python $SKILL/scripts/chart.py animate <line|bar|scatter|sparkline> \
  --duration SEC --frames N --json '<data>'

python $SKILL/scripts/chart.py record demo.cast --cmd 'glyph-arts art DEMO' --duration 10
python $SKILL/scripts/chart.py record-replay demo.cast --output demo.gif

python $SKILL/scripts/chart.py to-hyperframes \
  --json '[{"label":"x","x":[1,2,3,4,5],"y":[10,20,15,30,25]}]' \
  --frames 30 --duration 5 --output-dir ./hf-demo

Chat drawing front door:

python $SKILL/scripts/chart.py chat image --file photo.jpg --width 80 --height 30
python $SKILL/scripts/chart.py chat photo.jpg --image-style retro-art
python $SKILL/scripts/chart.py chat incplot --json 'name,value\nA,3\nB,7'
python $SKILL/scripts/chart.py chat sdr spectrum --json '{"freq":[99.0,99.3],"power":[-93,-42]}'
python $SKILL/scripts/chart.py chat sequence --json 'Client->Server: GET /health'
python $SKILL/scripts/chart.py chat mermaid --json 'graph LR\nA[开始] --> B[完成]'
python $SKILL/scripts/chart.py chat diagram note --json 'NOTE\nCache refresh required'
python $SKILL/scripts/chart.py chat textplot --json '{"expr":"sin(x) / x","xmin":-20,"xmax":20}'
python $SKILL/scripts/chart.py chat turtle --json '{"commands":[["forward",30],["right",90],["forward",20]]}'
python $SKILL/scripts/chart.py chat graph --json 'Client -> API\nAPI -> DB'
python $SKILL/scripts/chart.py chat formula --json '\int exp(-x^2) dx = \sqrt{\pi}'
python $SKILL/scripts/chart.py chat formula-pretty --json '(a+b)/(c+d)'
python $SKILL/scripts/chart.py chat effects

chat image implies --chat; chart commands imply --no-color.

stdin pipe (for large data):

echo '<json>' | python $SKILL/scripts/chart.py <type>
cat data.json  | python $SKILL/scripts/chart.py line

file input:

python $SKILL/scripts/chart.py bar --file path/to/data.json

check dependencies:

python $SKILL/scripts/chart.py --check-deps

Width defaults to terminal width ($COLUMNS). Override with --width 120.

Decision Tree -- Which Chart to Use

What is your data shape?
|
+-- Time series / sequence
|   +-- Unknown JSON/CSV/TSV shape     -> incplot
|   +-- Trend over time              -> plotext line
|   +-- Volume/count per period      -> plotext bar
|   +-- OHLC financial data          -> plotext kline
|   +-- Sparse scientific signal     -> uniplot
|
+-- Distribution / proportion
|   +-- Parts of a whole (<12 slices) -> rich pie
|   +-- Frequency distribution        -> plotext hist
|   +-- Two variables correlated      -> plotext scatter
|
+-- Comparison across categories
|   +-- Side-by-side bars             -> plotext bar (grouped -> multibar)
|   +-- Ranked list with scores       -> rich table
|   +-- Performance gauge (0-100)     -> rich gauge
|
+-- Hierarchy / tree structure        -> rich tree
|
+-- Density / matrix
|   +-- 2D correlation matrix         -> plotext heatmap
|   +-- RF spectrum trace             -> spectrum
|   +-- RF waterfall history          -> waterfall
|
+-- Structure / diagram text
|   +-- Formula / sequence / tree     -> diagram (Diagon backend when installed)
|   +-- Flowchart / DAG / planar graph -> diagram
|
+-- Continuous curve / function       -> drawille curve / textplot / turtle
|
+-- Multiple metrics at once          -> rich dashboard
|
+-- Inline sparkline (1 row)          -> sparkline
|   +-- Claude Code statusLine        -> sparkline --statusline
|
+-- Progressive reveal in terminal    -> animate line/bar/scatter/sparkline
|
+-- MP4/WebM/high-quality video       -> to-hyperframes, then npx hyperframes render
|
+-- Network / graph topology          -> graph
|
+-- Large ASCII label / banner        -> banner
|
+-- Styled text art / framed wordmark -> art

Claude Code CLI Compatibility

Trigger keywords:

• Claude Code statusline, statusLine.command, single-line metric -> use sparkline, indicator, or gauge with --statusline.
• OSC 8, terminal hyperlink, clickable title -> add --link-title URL; for line/scatter series labels add --link-data URL.
• Claude theme, dark-ansi, light-ansi, ~/.claude/themes -> use --theme claude-dark-ansi or --theme claude-light-ansi.
• subagent colors, agent rainbow, red blue green yellow purple orange pink cyan -> use --theme subagent-rainbow for multi-series charts.
• markdown table, GFM, Claude markdown render -> use table --output table.md.

Claude decision tree:

Need output inside Claude Code?
|
+-- Draw in the chat transcript        -> chat image|bar|line|spectrum|waterfall ...
+-- Status line shell command         -> sparkline/indicator/gauge --statusline
+-- Clickable terminal reference      -> --link-title URL or --link-data URL
+-- Match current Claude ANSI theme   -> --theme claude-dark-ansi or claude-light-ansi
+-- Match subagent color names        -> --theme subagent-rainbow
+-- Render table as markdown          -> table --output result.md
+-- Fullscreen TUI requested          -> dashboard/rich_live only when the user accepts TUI behavior

Chart Types Reference

Engine: incplot (1 type)

Engine: plotext (15 types)

Engine: SDR (2 types)

Engine: rich (7 types)

Engine: diagram (1 type)

Engine: drawille / textplots Braille (3 types)

Engine: hires (1 type) — 24-bit Braille

Engine: radar (1 type) — Polar Braille

Engine: plotille (1 type)

Engine: uniplot (1 type)

Engine: textcharts (9 types)

Zero-dependency, 15 chart types with ANSI colors. Install: pip install "glyph-arts[textcharts]" or pip install textcharts.

Engine: media (Pillow/chafa + ffmpeg) -- 2 types

Charts use a native Python engine. Image can render through Pillow as plain chat-safe text, or through chafa for 24-bit truecolor terminal rendering. Video needs ffmpeg plus chafa. These types take a filesystem path via --file, not JSON data.

Formula source is not an image. If source text is available, use glyph-arts chat formula for compact Unicode math or glyph-arts chat formula-pretty for SymPy-backed multi-line fractions, integrals, sums, and roots. Rasterize only screenshots/scans; for white-page material in dark terminals, use the image path with --invert.

Rationale for chart/media split: the native curve renderer connects every consecutive point-pair via Bresenham, which fills silhouettes into blobs when fed pixel data. chafa is purpose-built and superset of timg/viu on Windows. HANDOFF 2026-04-14 records the full architectural decision.

Misc (4 types)

Trigger keywords for art: wordmark, figlet, framed text, gradient text, decorated ASCII, composable text art.

Trigger keywords for animate: animation, animated chart, progressive reveal, terminal playback, cursor-home redraw.

Trigger keywords for record: record terminal, asciinema, cast file, terminal recording, replay export, gif export, svg export.

Trigger keywords for to-hyperframes: 视频, video, mp4, webm, 动画, motion, GSAP, launch, demo, hyperframes.

Video output decision tree:

• User wants GIF + short demo -> use glyph-arts record + glyph-arts record-replay
• User wants MP4 + high quality video -> use glyph-arts to-hyperframes + npx hyperframes render
• User wants embed README -> use record-replay --output .gif because GIF auto-plays in GitHub README
• User wants embed blog HTML -> use record-replay --output .svg for vector scaling

Output Contract

Success: exit code 0, chart rendered to stdout.

Failure modes:

AI parsing rule: always check exit code first. If non-zero, read stderr for structured error tag.

Size & Performance Limits

Over limit? Use --file + --sample <n> to auto-downsample.

AI Usage Rules

DO

• Use sparkline for a single inline metric in the middle of analysis
• Use dashboard when presenting 3+ related metrics simultaneously
• Use --file or stdin pipe when data exceeds 200 characters in JSON string form
• Use drawille curve when signal continuity matters (audio, sensor, physics)
• Use rich table when the user needs to read exact values
• Use chat graph for network topology, DAGs, dependency maps, and DOT/GraphML
• Use --sample N to downsample large datasets before rendering

DO NOT

• Do not pass more than 500 rows via --json inline -- use --file instead
• Do not use plotext heatmap for data with more than 20x20 cells
• Do not use rich pie with more than 12 slices -- switch to bar
• Do not call banner except for final result banners or section headers
• Do not generate a chart without a --title when presenting analysis results

Examples

Time series:

python $SKILL/scripts/chart.py line \
  --json '[{"label":"DAU","x":[1,2,3,4,5],"y":[100,120,115,130,125]}]' \
  --title "Daily Active Users"

Multi-series:

python $SKILL/scripts/chart.py line \
  --json '[{"label":"Revenue","y":[100,120,90,140]},{"label":"Cost","y":[80,95,75,110]}]' \
  --title "P&L Trend"

Pie chart:

python $SKILL/scripts/chart.py pie \
  --json '{"labels":["Equity","Bond","Cash"],"values":[60,30,10]}' \
  --title "Asset Allocation"

Dashboard (3 panels):

python $SKILL/scripts/chart.py dashboard \
  --json '{
    "panels": [
      {"type":"gauge","data":[{"label":"CPU","value":73,"max":100}],"title":"CPU"},
      {"type":"sparkline","data":{"values":[1,3,5,2,8,4,6]},"title":"Load"},
      {"type":"table","data":{"columns":["Host","Status"],"rows":[["web-01","OK"],["db-01","WARN"]]},"title":"Services"}
    ]
  }' \
  --title "System Health"

Large file:

python $SKILL/scripts/chart.py scatter \
  --file ./data/million_points.json \
  --sample 5000 \
  --title "Correlation"

From pipe:

cat metrics.json | python $SKILL/scripts/chart.py bar --title "Benchmark Results"

K-line from DuckDB:

python $SKILL/scripts/chart.py kline \
  --title "600519 K-line" --width 80 --height 24 \
  --duckdb "SELECT trade_date,open,high,low,close FROM stock_daily WHERE ts_code='600519.SH' ORDER BY trade_date DESC LIMIT 30" \
  --db /path/to/data.duckdb

Anti-patterns (don't do these)

# BAD: inline 10000-row JSON will crash the shell
python $SKILL/scripts/chart.py line --json '[...10000 items...]'
# GOOD:
python $SKILL/scripts/chart.py line --file data.json

# BAD: pie chart with 20 slices is unreadable
python $SKILL/scripts/chart.py pie --json '{"labels":["A","B",...20 items...],"values":[...]}'
# GOOD: switch to bar for many categories
python $SKILL/scripts/chart.py bar --json '{"labels":[...],"values":[...]}' --orientation horizontal

# BAD: no title in analysis context
python $SKILL/scripts/chart.py bar --json '{"labels":["Q1","Q2"],"values":[10,12]}'
# GOOD:
python $SKILL/scripts/chart.py bar --json '{"labels":["Q1","Q2"],"values":[10,12]}' --title "Q1 vs Q2 Revenue"

Dependencies

pip install plotext rich drawille uniplot pyfiglet sparklines duckdb pandas networkx phart
# optional: LTTB shape-preserving downsampling (--sample for line/scatter/step/uniplot)
pip install lttb
# optional: Textual TUI dashboard (scripts/dashboard.py)
pip install textual

Auto-install check:

python $SKILL/scripts/chart.py --check-deps
# prints OK or lists missing packages

DuckDB Integration

Textual TUI Dashboard

scripts/dashboard.py — standalone multi-panel dashboard (separate from chart.py).

python $SKILL/scripts/dashboard.py --demo                        # interactive Textual TUI
python $SKILL/scripts/dashboard.py --demo --no-interactive       # Rich static fallback (pipe-safe)
python $SKILL/scripts/dashboard.py --file config.json           # load panel config from file
python $SKILL/scripts/dashboard.py --json '{"panels":[...]}'    # inline JSON

# Panel types: gauge | sparkline | table | metric | bar
# Layout: auto-grid (<=4 panels -> 2col, >4 -> 3col) or manual via panel["row"]
# Live refresh: add "refresh_interval": 5 (seconds) to config
# Bindings: q=quit, r=refresh

Falls back to Rich static output if textual is not installed or stdout is not a tty.

Integration Notes

• Pipe-friendly: all output is pure stdout, errors go to stderr only. Safe to pipe.
• Session logging: set CLI_CHARTS_LOG=1 to append render history to .chart_history.jsonl.
• NO_COLOR: respects NO_COLOR env var (https://no-color.org) and --no-color flag.
• LTTB sampling: --sample N uses Largest-Triangle-Three-Buckets for line/scatter/step/uniplot (shape-preserving), OHLC group aggregation for kline, uniform stride fallback when lttb not installed.