Skip to content

Run the React Starter

Use this starter to try Maelstrom in a new React app. The local walkthrough follows predefined requests. It includes the app and Engine, and needs Bun. You do not need a model account or API key for this walkthrough.

Clone and run

Section titled “Clone and run”

  1. Open the React starter repository. Select Use this template to create your own repository, then clone it. To try the example directly:

    Terminal window
    git clone https://github.com/maelstrom-co/react-starter.git
    cd react-starter

  2. Install dependencies and check the source:

    Terminal window
    bun install --frozen-lockfile
    bun run typecheck

  3. Start the app and Engine:

    Terminal window
    bun run dev

  4. Open http://127.0.0.1:5173. Expect a task list and launch note.

Try the workflow

Section titled “Try the workflow”
  1. Choose Rearrange the workspace. The note opens its editor and gets more space. Edit the note directly.
  2. Choose Run an action. Expect Prepare the launch in the task list. The Engine response names the declared addTask action; the React app’s handler changes the data.
  3. Complete a task yourself, then choose Restore the layout. The note returns to its preview. Your edited note and task state remain in the app.
  4. Resize the window. Narrow containers stack the components. The added task remains a single item; resizing does not repeat the action.

The same components stay interactive throughout the walkthrough. Local mode accepts the example requests, including a different quoted title in Add "your task" to my tasks. Other text returns guidance.

Stop both servers with Ctrl+C. React and CSS edits update in the browser. Server edits restart the Engine. Reloading resets the app’s in-memory task and note data. Restarting the server clears its local history.

For a copy from this documentation build, download the source archive and run the same commands from the extracted directory.

Change one capability

Section titled “Change one capability”

src/workspace.ts defines the views, action, and initial layout. src/App.tsx owns the React components and application data. local-planner.ts selects among the declared capabilities for the walkthrough. server.ts hosts the Engine and validates HTTP input.

Change one renderer or declaration and repeat the workflow. Keep data and business rules in the app’s handlers. This local example does not configure production authentication, durable storage, or deployment.

Use a live model

Section titled “Use a live model”

The optional live mode uses OpenAI’s gpt-6-luna. Follow Connect OpenAI in the starter README to create .env.local and run bun run dev:live. Keep the API key on the server. Live requests send your intent, recent conversation, and workspace structure to OpenAI and can incur API charges. Loading and resizing the workspace make no model calls.

For an existing app, use Build with an agent to select a first integration and review its plan.