ggts
Navigate
On this page

Charts in agent sandboxes

Author a chart as data, aesthetics, and layers. The PortableSpec JSON is the artifact: the CLI checks and renders it without a browser, and React or Svelte can display the same spec in an application.

Install the feedback loop

In the sandbox project, install the CLI and skill at matching versions:

npm install --save-dev --save-exact @ggts-sh/[email protected] @ggts-sh/[email protected]

Keep package.json and the lockfile with the project. Install dependencies when preparing a sandbox, before disconnecting it from the network. Rendering local JSON requires no model service, browser, or framework installation.

Point the agent at node_modules/@ggts-sh/skill/SKILL.md. Add that instruction to the project's agent instructions, or copy the package directory into the skill directory used by your agent. Refresh copied files after each package upgrade; updating a dependency alone does not refresh a copy. The package has one shared grammar and separate React/Svelte references.

Give the agent a complete task

Read node_modules/@ggts-sh/skill/SKILL.md. Make a column chart of annual sales:
2023: 12, 2024: 18, 2025: 25. Save the complete PortableSpec to chart.json.
Run npm exec -- ggts check chart.json, read its diagnostics, and fix any errors.
Render chart.svg with npm exec -- ggts render chart.json and inspect the chart.

Here is the complete expected chart structure, saved as chart.json:

{
  "data": {
    "values": [
      {
        "year": "2023",
        "sales": 12
      },
      {
        "year": "2024",
        "sales": 18
      },
      {
        "year": "2025",
        "sales": 25
      }
    ]
  },
  "aes": {
    "x": {
      "field": "year"
    },
    "y": {
      "field": "sales"
    }
  },
  "layers": [
    {
      "geom": "col"
    }
  ],
  "scales": {
    "x": {
      "type": "band"
    }
  },
  "labs": {
    "title": "Annual sales",
    "x": "Year",
    "y": "Sales"
  }
}

Run the same commands yourself to verify the setup:

npm exec -- ggts check chart.json
npm exec -- ggts render chart.json > chart.svg

check runs the rendering pipeline and suppresses SVG output. render writes SVG to stdout. Both write JSON Lines diagnostics to stderr. Exit 3 means an invalid spec; 2 means invalid input or usage; 1 means the pipeline or renderer failed. Exit 0 can still carry warnings and advisories worth reading. Keep stdout and stderr separate so diagnostic text does not enter the SVG file.

Repair, then inspect

Validation errors identify a code, JSON path, and suggested fix. Apply a relevant fix.example at its path and check again. Read warnings about data, scales, and chart quality against the user's intent. Then open the SVG and inspect labels, axes, marks, and the story the chart tells.

The error catalog, advisories, and CLI reference explain the machine-readable feedback. The schema is at /schema/v0.json; the documentation index is at /llms.txt, with the corpus at /llms-full.txt.

Bring the chart into an application

Install the adapter for the target application and pass this spec to GGPlot. Call registerAll() once for spec-driven charts. Follow the React and Svelte quickstarts, or author the same grammar with the TypeScript builder and component children.

Inspection, selection, zoom, custom tooltips, and linked views are host behavior. Test them in a mounted browser application: CLI success does not verify framework callbacks, keyboard access, or hydration.

Docs