Hyperchart

Durable, typed statechart workflows for agents and scripts.

Hyperchart runs long-lived work as an explicit statechart. The chart defines what may run, which event advances it, what data crosses each transition, and how a run can be reconstructed after a crash.

Choose a package

Package	Use it for
@surprisal/hyperchart	Chart authoring, the pure machine, replay, the generic runtime, and host-neutral models.
@surprisal/pi-hyperchart	The Pi extension, /hyperchart, agent tools, terminal UI, and React inspector.
@surprisal/claude-hyperchart	The Claude Code plugin: hyperchart_* MCP tools, agent actions as Claude sessions, browser inspector, steering.

All packages require Node.js 22.19 or newer. The host packages depend on the same version of the core package.

Install

From npm

Install the core package in a TypeScript or Node.js project:

npm install @surprisal/hyperchart

Install the complete Pi integration, including the extension, tools, inspector, and bundled skill:

pi install npm:@surprisal/pi-hyperchart

For durable production runs, pin both packages to the same exact version.

From a local checkout

git clone https://github.com/surprisal-io/hyperchart.git
cd hyperchart
npm install
npm run build
pi install "$PWD/packages/pi-hyperchart"

Pi loads the local package in place, so later source changes remain available after rebuilding. Use npm run check before relying on a local checkout for real runs.

Run a chart in Claude Code

Load the plugin from a checkout and talk to Claude — charts live in .claude/hypercharts/, agent actions run as real Claude sessions, and hyperchart_view opens the live browser inspector:

claude --plugin-dir "$PWD/packages/claude-hyperchart"

See the Claude Code plugin guide for tools, locations, steering, and remote setups.

Run a chart in Pi

After installing the Pi package, create flat .pi/hypercharts/hello.chart.ts or bundle entrypoint .pi/hypercharts/hello/chart.ts:

import { artifact, chart, final, script } from "@surprisal/hyperchart";

export default chart({
  kind: "chart",
  id: "hello",
  initial: "write",
  states: {
    write: {
      kind: "state",
      action: script("node", [
        "-e",
        `require("node:fs").writeFileSync("hello.txt", "Hello from Hyperchart\\n")`,
      ], {
        artifacts: { greeting: artifact("hello.txt") },
      }),
      transitions: { DONE: "done" },
    },
    done: final(),
  },
});

A successful script with one non-FAILED transition emits that event implicitly. Ask Pi to inspect the chart with hyperchart with action: "inspect", then start it:

Use hyperchart action=inspect on .pi/hypercharts/hello.chart.ts
/hyperchart run .pi/hypercharts/hello.chart.ts

The run writes hello.txt and records its history under ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/hypercharts/runs/.

Self-contained bundles may include chart-private agents/, extensions/<name>/index.ts, scripts, and guards. See Pi extension: self-contained bundles.

Read Run your first chart for installation checks, expected output, agent setup, and troubleshooting.

What is durable

A run appends semantic facts to log.jsonl: arguments, action invocations, accepted events, map spawns, validation outcomes, and deadline firings. Current state is projected from those facts and the chart definition. It is not restored from a mutable checkpoint.

This makes crash recovery inspectable, but it does not undo external effects. A process may crash after a script or agent caused an external change and before the completion fact was appended. Read Recovery and safety before overriding replay warnings or rewinding a run.

Inspector

The Pi package includes a terminal view and a React inspector built from canonical host models. Static chart information and runtime overlays remain separate: reusable agent cards show definition metadata, while a selected run state's Runtime section owns its live-session controls. Map actions held behind a concurrency limit appear as waiting, not as running sessions.

Architecture

The pure machine requests facts and effects; it does not call Pi directly. The Pi package supplies the runner, agent executor, commands, tools, terminal UI, and React UI. See Architecture for the execution loop and formal-model boundary.

Documentation

• Run your first chart
• Author charts
• Compose nested, parallel, and map states
• Use the Pi extension
• Operate and recover runs
• Embed the runtime or React inspector
• Complete API reference
• DSL reference and examples
• File contracts and limitations
• Develop and release

Hyperchart is experimental. Pin exact package versions for durable runs and keep the chart source that produced each log.