---
slug: "surprisal-pi-hyperchart"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/surprisal-io/hyperchart@main/README.md"
repo: "https://github.com/surprisal-io/hyperchart"
source_file: "README.md"
branch: "main"
---
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`](https://github.com/surprisal-io/hyperchart/tree/HEAD/packages/hyperchart) | Chart authoring, the pure machine, replay, the generic runtime, and host-neutral models. |
| [`@surprisal/pi-hyperchart`](https://github.com/surprisal-io/hyperchart/tree/HEAD/packages/pi-hyperchart) | The Pi extension, `/hyperchart`, agent tools, terminal UI, and React inspector. |
| [`@surprisal/claude-hyperchart`](https://github.com/surprisal-io/hyperchart/tree/HEAD/packages/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:
```sh
npm install @surprisal/hyperchart
```
Install the complete Pi integration, including the extension, tools, inspector, and bundled skill:
```sh
pi install npm:@surprisal/pi-hyperchart
```
For durable production runs, pin both packages to the same exact version.
### From a local checkout
```sh
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:
```sh
claude --plugin-dir "$PWD/packages/claude-hyperchart"
```
See the [Claude Code plugin guide](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/claude-code.md) 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`:
```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:
```text
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//index.ts`, scripts, and guards. See [Pi extension: self-contained bundles](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/pi.md#self-contained-bundles).
Read [Run your first chart](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/quickstart.md) 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](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/safety.md) 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](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/architecture.md) for the execution loop and formal-model boundary.
## Documentation
- [Run your first chart](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/quickstart.md)
- [Author charts](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/core-authoring.md)
- [Compose nested, parallel, and map states](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/composition.md)
- [Use the Pi extension](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/pi.md)
- [Operate and recover runs](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/safety.md)
- [Embed the runtime or React inspector](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/integration.md)
- [Complete API reference](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/api/README.md)
- [DSL reference and examples](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/api/dsl.md)
- [File contracts and limitations](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/reference.md)
- [Develop and release](https://github.com/surprisal-io/hyperchart/blob/HEAD/docs/development.md)
Hyperchart is experimental. Pin exact package versions for durable runs and keep the chart source that produced each log.