Coding agents

On this page

Uitive is built to be integrated by a coding agent: every step is a command the agent can run and check, a playbook says in what order, and uitive check is the gate. Every page starts as a region, so the application works unchanged from the first minute. Three coding agents integrated Excalidraw, Medusa Admin and Grist this way, in 37 to 54 minutes each: see Findings.

Start

In the application's package:

sh
npx uitive detect   # what the project uses; at a monorepo root, where to set up
npx uitive init     # packages, the Uitive folder and the agents' configuration

Then ask the agent to integrate Uitive. init installs the playbook, a skill named integrate-uitive, which takes the agent from the contract to bindings, pages, the kit and checks, one checked step at a time.

What init writes

init never replaces a file. In the Uitive folder, src/uitive/ when there is a src folder and uitive/ otherwise:

FileWhat it holds
contract.tsThe contract, with the home page as one region
bindings.tsThe bindings, typed by the contract, reading with the application's own session
client.tsThe client and its store
kit.tsxThe kit, mapped to the design system it found (React only)
server.tsThe planner's handler, when the project has a server
api.generated.tsSources, actions and endpoints from a small API description
curation.jsonWhat to keep from a large API description, for you or the agent to fill in

init --dir app/uitive puts the folder elsewhere, such as inside the only folder the build compiles; package.json records it as uitive.dir, where every command finds it. With Next.js, init also writes api/uitive/[kind]/route.ts in app, or in src/app when there is one.

At the repository's root, it configures the coding agents it finds: Claude Code (.mcp.json and the skill), Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json). It adds its MCP server to a configuration that exists, keeping everything else in it and its indentation; a uitive server already there, perhaps written by hand, it keeps as it is. One it can't parse, such as JSON with comments, it leaves alone and says what to add by hand. With none of these found, it configures Claude Code and says so: Codex, which it recognizes by an AGENTS.md, has nothing it can configure. --mcp takes the server's command quoted as in a shell, such as --mcp 'node "/My Projects/uitive/packages/mcp/dist/bin.js"', or as a JSON array of words. --no-agents leaves them all alone.

The commands

Every command takes --json for agents, --cwd <dir> for the project's root, and --help. Each exits with 0 when it worked, and with 1 when a required option is missing, when something goes wrong, or as below.

CommandWhat it doesAlso exits with 1 when
detectLists what the project uses: package manager, UI library, framework, router, design system, server, API descriptions and coding agents
initSets Uitive up. --dir, --openapi, --packages, --no-install, --no-agents, --mcp <command>installing failed
survey --openapi <spec>One line per source an OpenAPI 2.0, 3.0 or 3.1 description yields, to curate from. --curationthe description has problems
generate sources --openapi <spec>Writes api.generated.ts from the description and curation.json. --curation, --out, --dry-rungenerating failed
generate blocks <file#Component>…Writes blocks.generated.ts from components' props. --out, --checkthere are problems, or with --check, drift
discover --url <url>Crawls the running application and writes discovery.json. --pages, --per-route, --storage-state, --chrome, --outno page could be read
checkThe gate: contract, JSON, request schemas and bindings, with warnings about labels and coverage. --contract, --bindingsany check fails; warnings don't

Curation

An API description describes everything; an interface shows a part. Past 40 sources or 200 actions, planning gets worse, so generate sources asks for a curation first. Curating is three steps:

  1. uitive survey --openapi <spec> prints one line per source: the fields kept and left out, its filters, search, sorting and paging, and its actions, then what was skipped and why.
  2. curation.json in the Uitive folder keeps what the frontend shows, names things the way its people do, and lifts nested values people look at.
  3. uitive generate sources --openapi <spec> writes the sources and actions, which the contract spreads in. Rerun it after every change to the curation, and never edit the generated file.
json
{
  "default": "exclude",
  "sources": {
    "orders": {
      "include": true,
      "label": "Orders",
      "description": "Orders placed by customers, with their payment and fulfillment status",
      "keywords": ["purchase", "sale"],
      "fields": ["display_id", "email", "total", "currency_code", "payment_status", "created_at"],
      "labels": { "display_id": "Order", "created_at": "Placed" },
      "pick": { "customer_name": "/customer/first_name" },
      "query": { "fields": "*customer" },
      "title": "display_id",
      "summary": ["total", "payment_status"],
      "scan": 500,
      "ttl": 30
    }
  },
  "actions": {
    "orders.cancel": { "confirm": "cancel order" },
    "fulfillments.create": {
      "effect": "write",
      "reason": "Fulfillments can be canceled until they ship"
    },
    "orders.archive": { "include": false }
  }
}

Choices survive every regeneration. An action's effect can be raised freely, and lowered only with a reason: destructive stays destructive unless the backend makes it safe. The CLI's README has every key: Curation. In Claude Code, the plugin's curator agent does this step: it reads the survey and the frontend's API calls, and writes the curation.

Amounts in minor units are read with ISO 4217's decimal places. When an API's minor units differ for some currencies, such as Icelandic krona in hundredths and Malagasy ariary in whole units, the curation says so once, for every money field and param in minor units:

json
{ "money": { "digits": { "ISK": 2, "MGA": 0 } } }

Discovery

uitive discover --url http://localhost:5173/ crawls the running application with Playwright, following same-origin links and never pressing anything. It proposes routes, with row keys turned into parameters, a region per route, lists from navigation and toolbars, which buttons match the contract's actions, and the buttons that open menus it doesn't open, which it asks the page for (aria-haspopup, aria-expanded), since a snapshot marks a menu's button only while the menu is open. Buttons in dialogs, their toolbars and tables included, and sort buttons are never actions, and a generic verb or a dismissal alone, such as "Create" or "Cancel", never matches a longer action. A table's row buttons count only when their names repeat from row to row, so a button that shows a row's data, such as a customer's name, is never read.

  • It needs playwright, or playwright-core with --chrome to use the installed Chrome.
  • --storage-state <file> gives it a signed-in session, saved with Playwright.
  • It never navigates to another origin, not even through a redirect, and says which pages it skipped and why. A page that keeps polling gets a moment to settle instead of waiting for quiet.
  • It writes discovery.json in the Uitive folder, for the agent to turn into routes, regions and lists.

Native blocks

uitive generate blocks src/order-summary.tsx#OrderSummary writes block specs from components' TypeScript props, so redesigns can place the application's own components: literal unions become enums, optional props become required with their defaults described, and functions, content and objects are left out and reported. Run it with --check in CI. Pages shows how to render them.

The check

uitive check loads the contract and the bindings in Node, through the project's tsconfig paths, and checks that they hold: see Contracts. Labels two actions share, or that don't find their source, are warnings, worth fixing but not failures. It prints what the integration covers, such as "Coverage: 0 sources; 10 actions, 0 with effects; 1 route, 1 page, 1 region, 2 lists, 0 choices.", so an agent can report it. Keep the contract importable on its own: aliases only the bundler knows don't resolve in Node.

MCP

@plurid/uitive-mcp offers the same steps as Model Context Protocol tools, for agents that prefer tools to a shell:

json
{ "mcpServers": { "uitive": { "command": "npx", "args": ["-y", "@plurid/uitive-mcp"] } } }
ToolWhat it does
uitive_detectWhat the application uses. Start here
uitive_initSets Uitive up; installs packages only when install is true
uitive_openapi_surveyThe survey of an API description
uitive_generate_sourcesSources, actions and endpoints from the description and the curation
uitive_generate_blocksBlock specs from components' props; with check, reports drift
uitive_discoverCrawls the running application
uitive_checkThe gate, with coverage
uitive_preview_planWhich sources and actions a request would plan over, and how large its schema and prompt are, without calling the model

No tool reads or writes outside the project's root, symbolic links resolved: a tool's paths are relative to its cwd, the application's package, and init configures the coding agents at the nearest repository root inside the project's root, else at the root itself, never above it. Generating writes only *.generated.ts files in the Uitive folder, and discovery only a .json file there. API descriptions come from files, and discovery crawls only this machine's hosts (localhost, *.localhost, 127.0.0.1, [::1]), unless the server starts with --allow-network. The packages the project's own code imports, such as its contract's, resolve as Node resolves them for the project.

Claude Code

The plugin bundles the playbook, a skill that checks an integration and says what to fix, the curator agent and the MCP server. Add this repository as a marketplace, then install it:

/plugin marketplace add plurid/uitive
/plugin install uitive@plurid-uitive

init already configures Claude Code in a project; the plugin brings the same to every project.