# Graph

> This skill should be used when the user asks to 'graph a file', 'plot data', 'visualize this file', 'chart this', 'show me a graph of', 'plot the distribution', 'graph these metrics', or invokes '/graph'. It opens a live-updating terminal chart in a side pane driven by this conversation.

- Skill: `collinthefarmer/graph` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add collinthefarmer/graph`
- Raw SKILL.md: https://api.skillmd.com/api/skills/collinthefarmer/graph/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: collinthefarmer (https://skillmd.com/u/collinthefarmer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/collinthefarmer/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:
```json
{
  "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:
```json
{
  "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

| Scenario | Path |
|----------|------|
| CSV/JSON, plot specific columns | Write-first |
| Log file, extract and plot a field | Write-first |
| Small dataset, filter and visualize | Write-first |
| Rolling average or aggregation | Script |
| File >5000 rows | Script |
| Binary format (parquet, sqlite) | Script |

## 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