Overview

chartcoach represents visualization design guidelines as structured, versioned catalog entries with source references. The Guideline Catalog lets applications and agents find relevant guidance, inspect the exact guideline text, and trace it back to its original sources.

Use the CLI, Python, and JavaScript APIs for programmatic catalog access. For agents, use chartcoach skills for retrieval and citation workflows, or MCP tools for direct catalog calls.

Browse the catalog

Start with table output when you want to inspect matching guidelines in a terminal:

uvx chartcoach@latest catalog query \
  --contains "legend" \
  --limit 3 \
  --format table

# Other query formats: json, jsonl, csv.

The table view is for reading candidate rows directly. Use the returned id when you need exact guideline text or citations.

Ground an answer

Use query or find to shortlist guideline ids, then read and cite exact entries before using them in an answer. Exact read and cite calls return the guideline text and source references for the answer to cite.

Run a query, then read and cite one returned guideline:

uvx chartcoach@latest catalog query --contains "legend" --limit 5 --format jsonl

uvx chartcoach@latest catalog read add-unlabeled-axis-ticks-to-continuous-color-keys \
  --source-detail minimal \
  --format json

uvx chartcoach@latest catalog cite add-unlabeled-axis-ticks-to-continuous-color-keys \
  --format json

Use the id from a selected JSONL row in later read and cite calls. The query and find commands, plus cc.search(), find candidate guidance for an answer. read returns the exact guidance to inspect, and cite returns the sources to name.

Why use chartcoach

1. Structured guidance: Each guideline has a stable id, role-marked sections, labels, and source references that agents and applications can address directly.
2. Traceable recommendations: read returns the exact guideline text, and cite returns the sources to name with the answer.
3. Programmatic access: The CLI, Python API, JavaScript loader, and SQL tables support terminal workflows, notebooks, services, and browser apps.
4. Agent-ready retrieval: chartcoach skills guide agents through retrieval and citation workflows, while MCP tools expose catalog calls to MCP clients.
5. Custom catalogs: Build and validate a catalog instance when your team needs its own guideline set, release metadata, or source bundle.

Next steps