Plot History Management

Search, retrieve, and export plots from the persistent history.

When to Use This Skill

Use this skill when the user:

• Asks about a plot they made before ("show me the scatter plot from yesterday")
• Wants to find a specific visualization ("find my sales chart")
• Needs to export a previous plot ("export that histogram to PNG")
• Asks what plots exist ("what plots have I made?")
• Wants to compare or reference earlier work

IMPORTANT: Check History First

Before recreating a plot from scratch, ALWAYS check if it already exists in history:

bun packages/core/src/cli-plot.ts history

This saves time and ensures consistency with what the user previously created.

CLI Commands

List All Plots

bun packages/core/src/cli-plot.ts history

Output:

Plot History:

ID              Date        Description
─────────────────────────────────────────────────────────────────────────
2024-01-26-001  2024-01-26  Scatter plot of price vs sqft by region - "Housing"
2024-01-26-002  2024-01-26  Histogram of income - "Income Distribution"
2024-01-27-001  2024-01-27  Line chart of revenue vs date by product - "Sales"

Total: 3 plot(s)

Search History

bun packages/core/src/cli-plot.ts history <search-term>

Searches across:

• Plot descriptions
• Data file names
• Geom types (scatter, histogram, line, etc.)

Examples:

bun packages/core/src/cli-plot.ts history scatter     # Find scatter plots
bun packages/core/src/cli-plot.ts history sales       # Find plots with "sales"
bun packages/core/src/cli-plot.ts history histogram   # Find histograms
bun packages/core/src/cli-plot.ts history iris.csv    # Find plots using iris.csv

Re-render a Plot

bun packages/core/src/cli-plot.ts show <plot-id>

Displays the plot in the terminal exactly as it was originally created.

Export a Plot

bun packages/core/src/cli-plot.ts export <plot-id> [output.html]

Creates an interactive HTML file with PNG/SVG download buttons.

Natural Language → Commands

history

history scatter

history sales

show 2024-01-26-001

history histogram

show <id>

history iris

export <id> iris-plot.html

history

export <id>

Workflow Examples

Example 1: "Show me the plot I made with the housing data"

# Step 1: Search for it
bun packages/core/src/cli-plot.ts history housing

# Output shows: 2024-01-26-001  Scatter plot of price vs sqft - "Housing Prices"

# Step 2: Display it
bun packages/core/src/cli-plot.ts show 2024-01-26-001

Example 2: "Export my histogram to PNG"

# Step 1: Find histograms
bun packages/core/src/cli-plot.ts history histogram

# Output shows: 2024-01-26-002  Histogram of income - "Income Distribution"

# Step 2: Export to HTML (user can download PNG from browser)
bun packages/core/src/cli-plot.ts export 2024-01-26-002 income-histogram.html

# Step 3: Tell user to open in browser and click "Download PNG"

Example 3: "What did I plot last week?"

# List all and filter by date visually
bun packages/core/src/cli-plot.ts history

# Look for entries with dates from last week in the output

Plot ID Format

IDs follow the pattern:

YYYY-MM-DD-NNN

• YYYY-MM-DD

  - Date the plot was created

• NNN

  - Sequence number for that day (001, 002, etc.)

Example:

2024-01-26-003

Provenance Information

Each stored plot includes:

• timestamp: When it was created
• dataFile: Path to the data file used
• command: The exact CLI command that created it
• description: Auto-generated summary of the plot
• geomTypes: List of geometries used (point, line, histogram, etc.)
• aesthetics: Mapped variables (x, y, color, etc.)

To see full provenance, read the plot file directly:

cat .ggterm/plots/2024-01-26-001.json

Tips

1. Be generous with search terms - The search is case-insensitive and matches partial strings
2. Check dates - If user says "yesterday" or "last week", look at the Date column
3. Multiple matches - If search returns multiple plots, ask user to clarify or show the list
4. Missing plots - If nothing matches, the plot may not exist; offer to create it

$ARGUMENTS