Cascade

A node-graph runtime with a visual Studio, for generative design. Built at FIELD.IO and used for our own work.

Before you start

You need Node 22.13 or newer. Check with node --version; if it is older, or missing, install it from nodejs.org or with brew install node.

macOS and Linux are what we run. Studio itself is a web app and works in any current browser.

Getting started

Install the CLI.

npm install -g @field/cascade

Make a sketch. This creates ~/Documents/Cascade/my-sketch and opens Studio in your browser.

cascade new my-sketch

Install the sketch's own dependencies. Do not skip this.

cd ~/Documents/Cascade/my-sketch
npm install

A global CLI is not enough on its own. Any node that touches files, images, a shell command or a Python stage imports from cascade/…, and that resolves from the sketch's own node_modules. Without this step those nodes fail at run time with Cannot find package 'cascade', while simpler graphs keep working — which makes it a confusing thing to debug later.

Reopen it any time, from the sketch folder or by name.

cascade .
cascade my-sketch

Working in Studio

Studio is dockable: a graph canvas, an inspector, a viewer, a code editor, logs, and panels a project defines itself. Tab adds a node, and the graph is a plain .cascade file you can commit and diff.

A sketch owns its own nodes as ordinary TypeScript under nodes/<Name>/index.ts, so anything you can write in a file you can wire into a graph. Read the AGENTS.md in your new sketch first — it is short, and written for both you and whatever coding agent you point at the folder.

Useful commands

cascade new <name>            create a sketch and open it
cascade .                     open the sketch in this folder
cascade node <Name>           scaffold a typed custom node
cascade run <graph.cascade>   execute a graph headlessly, no browser
cascade check <graph.cascade>  static check of types and structure
cascade projects <dir>        move where sketches live
cascade --help                all of it

A few things worth knowing

Some sketches need more than Node. Anything doing heavy image work has a Python stage and its own requirements file — check the sketch's README before assuming it is broken.
Studio serves on localhost by default. --host exposes it on your network for a browser on another machine, and that is for a trusted network only. Never put Studio on the public internet; it compiles and runs code from the project folder by design.
Credentials live in ~/.cascade/credentials.yaml, per machine, never in a graph.

Going deeper

doc/PROJECT_AUTHORING.md — how a project is laid out, and how to write nodes properly.
ARCHITECTURE.md — contracts, runtime, hosts, and why the dependencies point one way.
doc/Cascade Product Overview.md — what Cascade owns and what a project owns.