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:
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' configurationThen 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:
| File | What it holds |
|---|---|
contract.ts | The contract, with the home page as one region |
bindings.ts | The bindings, typed by the contract, reading with the application's own session |
client.ts | The client and its store |
kit.tsx | The kit, mapped to the design system it found (React only) |
server.ts | The planner's handler, when the project has a server |
api.generated.ts | Sources, actions and endpoints from a small API description |
curation.json | What 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.
| Command | What it does | Also exits with 1 when |
|---|---|---|
detect | Lists what the project uses: package manager, UI library, framework, router, design system, server, API descriptions and coding agents | |
init | Sets 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. --curation | the description has problems |
generate sources --openapi <spec> | Writes api.generated.ts from the description and curation.json. --curation, --out, --dry-run | generating failed |
generate blocks <file#Component>… | Writes blocks.generated.ts from components' props. --out, --check | there are problems, or with --check, drift |
discover --url <url> | Crawls the running application and writes discovery.json. --pages, --per-route, --storage-state, --chrome, --out | no page could be read |
check | The gate: contract, JSON, request schemas and bindings, with warnings about labels and coverage. --contract, --bindings | any 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:
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.curation.jsonin the Uitive folder keeps what the frontend shows, names things the way its people do, and lifts nested values people look at.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.
{
"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:
{ "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, orplaywright-corewith--chrometo 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.jsonin 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:
{ "mcpServers": { "uitive": { "command": "npx", "args": ["-y", "@plurid/uitive-mcp"] } } }| Tool | What it does |
|---|---|
uitive_detect | What the application uses. Start here |
uitive_init | Sets Uitive up; installs packages only when install is true |
uitive_openapi_survey | The survey of an API description |
uitive_generate_sources | Sources, actions and endpoints from the description and the curation |
uitive_generate_blocks | Block specs from components' props; with check, reports drift |
uitive_discover | Crawls the running application |
uitive_check | The gate, with coverage |
uitive_preview_plan | Which 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-uitiveinit already configures Claude Code in a project; the plugin brings the same to every project.