Graph

Graph — Interactive Terminal Data Visualization

Open a live plotext chart in a side pane and drive it from this conversation. Feed it any file — CSV, JSON, logs, or anything with extractable data — and explore it visually through conversation.

Quick Start

/graph <file> [instructions]

How It Works

1. Read the source file to understand its structure
2. Read ~/.claude/skills/runtime.json to get runtime_dir and data_dir
3. Choose a name for the graph session (default: source filename without extension)
4. Create the session directory: mkdir -p <runtime_dir>/claude-graph/<name>
5. Write current-data.json to that directory — a hook auto-opens the renderer pane
6. Optionally write current-config.json for custom presentation

That's it. The renderer appears in a right-side pane and updates live on every write.

Named Sessions

Different graph names open separate renderer panes, allowing side-by-side comparison:

/graph latency.csv          → writes to claude-graph/latency/
/graph errors.csv           → writes to claude-graph/errors/

Both charts coexist as graph/latency and graph/errors panes.

Data Protocol

current-data.json (required)

Column-oriented dataset:

{
  "columns": [
    {"name": "col_name", "type": "numeric|categorical|datetime|text", "values": [...]}
  ],
  "metadata": {"source_file": "...", "row_count": N}
}

current-config.json (optional)

The renderer infers graph type, axes, title, and labels from column types when no config is provided:

• categorical + numeric → bar chart
• datetime + numeric → line chart
• 2 numerics → line chart
• 1 numeric → histogram

To override or customize, write a config:

{
  "graph_type": "bar",
  "axes": {"x": "column_name", "y": "column_name"},
  "title": "...", "xlabel": "...", "ylabel": "...",
  "style": {"theme": "dark", "color_palette": ["green", "red"]},
  "options": {"sort_x": "value_desc", "limit": 10, "show_values": true}
}

Renderer-handled options (no agent computation needed):

• sort_x: "asc", "desc", "value_asc", "value_desc" — sorts the x-axis
• sort: true — shorthand for sort_x: "value_desc"
• limit: integer — show only the first N data points (after sorting)
• show_values: true — display values above bars (toggleable with v key)
• Large numbers on axes are auto-formatted (120000 → 120k)

For multi-series: "y": ["series_a", "series_b"]

Full schema: read references/data-protocol.md

Agent Protocol

You ARE the agent. Follow these rules:

Rule 1: Write-First for Simple Data

For most visualizations, write the JSON files directly using the Write tool:

1. Read the source file to understand its structure
2. Construct current-data.json with the columns and values needed
3. Write it to <runtime_dir>/claude-graph/<name>/current-data.json
4. Optionally write current-config.json for custom presentation

Suitable when:

• The source is CSV, JSON, logs, or structured text
• The file is under ~5000 rows
• No heavy computation is required

Rule 2: Script Fallback for Complex Transforms

When the visualization requires computation:

• Rolling averages, aggregations, resampling, statistical operations
• Very large files (>5000 rows)
• Binary formats (parquet, sqlite, etc.)

For these: check the library manifest, write a Python script, execute via Bash.

• Library: <data_dir>/claude-graph/library/
• Venv Python: <data_dir>/claude-graph/venv/bin/python3

Rule 3: Persist Novel Modules

After a successful extraction that required new script code, offer to save new parsers/transforms/extractors to the library.

Decision Guide

Renderer Keybindings

The chart pane accepts direct keypresses:

• n — next compatible graph type
• p — previous compatible graph type
• v — toggle value labels
• r — force reload
• q — quit renderer (closes pane)

Dependencies

Python packages (in venv): polars, pandas, numpy, plotext System: python3.11+, tmux Skills: pane (used by hook for renderer pane lifecycle) Setup: run setup.sh once to install hooks

References

• references/data-protocol.md — Full JSON schemas
• references/architecture.md — System design
• references/library-guide.md — Library module creation