Skip to content

Introduction

Most product interfaces assume that developers can predict the screen a user will need before the user asks for it. That works for fixed workflows, but it breaks down in AI-powered applications where the useful interface changes with the user’s intent, the available tools, and the space on screen.

Maelstrom orchestrates the components you designed. It’s an open-source library for AI-orchestrated UI: you author your components as Vessels — typed state machines with variants and size hints — and a model arranges, resizes, and invokes them on a spatial layout surface, by intent, in real time. It arranges the interface you designed; it never generates one.

The problem Maelstrom solves

Section titled “The problem Maelstrom solves”

Traditional UIs hardcode layouts, navigation flows, and component states at build time. Maelstrom keeps those pieces explicit, but moves the selection and arrangement decision to the engine at runtime. The result is not an LLM inventing arbitrary UI; it is an LLM choosing among the Vessels, variants, and actions your application already declared.

That matters for products such as dashboards, data explorers, multi-tool workspaces, and conversational applications. In those products, the user often asks for an outcome rather than a page name. Maelstrom gives the engine a safe catalogue of UI capabilities, then lets it assemble the right surface for the current request.

Intended audience

Section titled “Intended audience”

Maelstrom is designed for developers building AI-powered applications where the interface should adapt to user intent. It ships first-class React bindings alongside a framework-agnostic client, so you can start with React and still keep the orchestration boundary independent from the UI framework.

Use it when your product has multiple task-specific components and the right arrangement depends on what the user is trying to do. If your application has one fixed flow and no need for runtime layout decisions, a conventional UI will usually be simpler.

How it works

Section titled “How it works”
  1. You define Vessels — UI components with typed variants, minimum sizes, and actions the engine may invoke.
  2. The engine orchestrates — based on user intent and current chart state, it chooses actions and layout.
  3. The Chart renders — a grid or tiling layout positions the selected Vessels on screen.
App.tsx
import { createMaelstrom, vessel } from '@maelstrom-co/react';


const m = createMaelstrom({
  vessels: [weatherVessel, calendarVessel, taskVessel],
});


function App() {
  return (
    <m.Provider connector={connector}>
      <m.Chart />
    </m.Provider>
  );
}

Next steps

Section titled “Next steps”