node_modules/rivet-design/README.md

# Rivet

Rivet helps you explore multiple design directions for your web app. It opens a local visual editor, generates parallel variants, lets you refine with comments, and can send the chosen direction back into your project.

## Install

Run the installer from the project where you want AI agents to use Rivet:

```bash
npx -y rivet-design@latest install
```

Rivet requires Node.js 22.16+ (22.x) or 24+. The installer exits with an upgrade
message on older runtimes instead of continuing with an outdated Rivet
release.

Bare `install` reports the identified agent and returns a JSON confirmation request. Your agent asks you to confirm or choose Claude Code, Codex, Cursor, or Other in the conversation, then waits for your response. Nothing is installed until you choose. Installed agents are suggestions, not proof of which agent is running the command. Other agents have no automatic integration; Rivet explains that limit instead of configuring a different host.

Installation uses the invoked package without automatic updates or integration refreshes before confirmation. `npx -y rivet-design@latest install` obtains the latest package; `rivet update` and normal commands retain their update behavior.

After confirmation, your agent runs the returned explicit-target command, preserving attribution and installation options. To choose directly, use `install claude`, `install codex`, or `install cursor`. Use `install all` to configure every detected coding agent. Setup writes shared CLI guidance and host-specific command permissions and registers MCP unless `--no-mcp` is passed. File-based setup also works from desktop coding sessions without a separate agent CLI; the installer reports any unavailable MCP registration. After installing, start a new agent session. Use `/rivet` in Claude Code, `$rivet` or `/skills` → Rivet in Codex, or say "Open Rivet".

You can also run Rivet directly without a global install:

```bash
npx -y rivet-design@latest open --project /path/to/app
```

If installed globally, the package exposes the `rivet` binary:

```bash
rivet open --project /path/to/app
```

## Project library

Rivet opens one shared project library on your computer. Run `rivet open` inside a project to open its editor, or from a non-project directory to browse saved directions across projects. Projects register automatically when opened or created; **Open project…** also lets you choose an existing folder.

While Rivet is running, open `http://localhost:16060` in a browser and sign in with Google to reach the same library. Local development installs use port 16061. Set `RIVET_LIBRARY_PORT` to another port before `rivet open` if the default is occupied. Rivet reports a port conflict instead of moving silently. Opening a browser URL does not start the coordinator after a restart; run `rivet open` to start it.

Saved directions live in project bundles under `~/.rivet/library/production`. Their metadata and self-contained previews remain available when a working folder is missing. Editing still requires that folder. Existing histories are copied only after verification, and their source files are preserved. Switching projects in the browser does not change the project targeted by your terminal or agent.

## Automatic Updates

Published global installations check npm for a newer Rivet release before
CLI and MCP startup. Successful checks are cached for one hour. When an update
is available, Rivet installs it, refreshes existing MCP registrations and agent
guidance, and continues the original command through the updated CLI without a
prompt.

If the registry or npm is unavailable, Rivet reports the missed update on
stderr and continues with the installed version. Run `rivet update` to bypass
the cache and explicitly verify the installed version. Versions published
before automatic updates were introduced require one final
`npx -y rivet-design@latest install` migration.

Updated skill and rule files are available on disk immediately. An agent
session that already loaded them may need its normal restart or reload before
it uses the refreshed instructions.

At the start of a host-agent conversation that uses Rivet, the agent runs
`rivet version status` before opening the project. The command reports the
installed version, latest published version, and update availability without
changing the installation. The agent shares those versions, runs `rivet update`
when a release is available, and reports the outcome before continuing. If an
update fails, the agent reports the failure and can continue with the installed
CLI. This notice and update flow happens in the host-agent conversation, not
in the editor.

## CLI Agent Commands

Rivet's agent-facing commands print one JSON envelope on stdout, write progress to stderr, and do not prompt for input.

In Codex within the ChatGPT desktop app or in Claude Code Desktop, use `rivet open --project /path/to/app --no-browser` when the app has an in-app browser that can reach localhost. Open the exact returned `data.editorUrl` in that browser. In Claude Code Desktop, a user may need to select **Open in app** for the link. If the host has no usable in-app browser, run `rivet open` without `--no-browser` to launch the system browser. Always share the returned URL so the user can open it if browser navigation fails.

```bash
rivet version status
rivet open --project /path/to/app
rivet status --project /path/to/app
rivet variants start --project /path/to/app --instruction "try three hero layouts" --count 3
rivet wait <workId> --project /path/to/app --timeout 120
rivet variants list --project /path/to/app
rivet variants get <projectId>/<sessionId>:<variantId> --detail
rivet changes request --project /path/to/app --instruction "make the header coral" --element "#header"
rivet changes pull --project /path/to/app
rivet update
rivet stop --project /path/to/app
```

For a fresh project, create or use an empty directory, open Rivet there, then start variants with `--fresh`:

```bash
rivet open --project /path/to/new-app
rivet variants start --project /path/to/new-app --fresh --instruction "build a SaaS landing page" --count 3
```

For shell agents, pass caller metadata on each command when available:

```bash
rivet open --project /path/to/app --caller-agent cursor --caller-model <model> --caller-session <session-id>
```

## How It Works

1. `rivet open` starts or attaches to the local Rivet editor server for a project. It can attach to an existing dev server or start the app's standard `dev`, `start`, or `serve` script when possible.
2. The editor shows your app and variant previews in the browser. Agents use `rivet variants ...` and `rivet changes ...` to enqueue work.
3. Use `rivet wait`, `rivet status`, or `rivet status --watch` to observe progress.
4. Copy the chosen direction’s context and ask your coding agent to implement it in your project. Rivet preserves the prototype; your agent owns integration and verification.

If Rivet reports pull mode, staged work can be drained with `rivet changes pull --project <path>`, applied by the agent, then acknowledged with `rivet changes pull --project <path> --ack <leaseId>`.

## Supported Frameworks

- Next.js
- Vite
- Create React App
- Remix
- SvelteKit
- Static HTML

## Requirements

- Node.js 22.16+ (22.x) or 24+
- A shell-capable coding agent for agent-driven flows
- Git for variant branch/history features

## License

GPL-3.0-or-later