UI-graph

Your app generates its own verified behavioral map.
React · Vue · Angular · Next.js — screens as nodes, (event, guard, effect) transitions as edges.

Tests, docs, agents, and impact analysis are all views over one graph — and every edge says how much you can trust it.

UI-graph: from drafts, guesses, and rotting tests to a drafted graph, a triaged proposal queue, and witnessed Playwright suites

Your agent re-derives your app's navigation from source on every session — and a graph it guesses today can disagree with the one it guesses tomorrow. UI-graph computes the map once per commit, deterministically, then makes the LLM's additions earn their way in with runtime proof. The moat is not the word "map". It's the word verified.

Features

[!NOTE]
The core is model-free: no API key, no bundled LLM. Your coding agent (Claude Code, Cursor, Copilot) connects over MCP and brings its own model — the graph works offline and in LLM-restricted CI.


Deterministic extraction	ts-morph static analysis of react-router v5/v6/data-router, vue-router, Angular Routes, and Next.js file routes — every edge carries a `file:line` witness
Proof-gated verification	`report_observation(confirmed)` requires evidence (URL change, asserted dialog, screenshot on disk) + provenance, or it is rejected. A hallucinated confirmation cannot enter the graph
Trust tiers on every edge	`witnessed > proven > asserted > llm-verified > proposed > unknown` — projected on read, so an agent always knows how far to lean
The Tier-2/3 loop	The LLM proposes greedily (`propose`, quarantined), the runner drives a real browser (`uigraph verify`), and only the observation — never the guess — mints an edge
Honest coverage	`runtime-verified ⊆ verified ⊆ accounted` are never conflated; undrivable edges are parked with a written reason, and a re-map demotes stale witnesses for re-confirmation
Agent-native	27 MCP tools + an installable agent kit (`uigraph kit install`), a one-command dashboard, Playwright spec generation, and structural + temporal graph diffs

Quick start

Install the CLI and map your app (adapter auto-detected from package.json):

npm i -g @ui-graph/cli          # or: pnpm add -g @ui-graph/cli
uigraph map ~/work/your-app --controls

Open the dashboard — one command, serves UI + API and opens your browser:

uigraph dash                 # all registered projects, switchable in the topbar

Verify against the running app — drive uncertain transitions in a real browser; confirmations need proof:

uigraph login http://localhost:3000 --out auth.json    # log in manually once (any auth scheme)
uigraph verify ~/work/your-app --app-url http://localhost:3000 \
  --storage-state auth.json --until-done
uigraph verify ~/work/your-app --app-url http://localhost:3000 --all   # sweep static proofs too

Connect your agent over MCP:

uigraph mcp ~/work/your-app        # stdio server for Claude Code / Cursor / Copilot
uigraph kit install --claude       # rules + guides + the reconciliation-loop playbook

In your MCP client config (e.g. Claude Code / Cursor):

{ "mcpServers": { "uigraph": { "command": "uigraph", "args": ["mcp", "/abs/path/to/your-app"] } } }

Every workspace is a single uigraph.db (SQLite, no native deps) you can commit — teammates and CI read the same verified graph without re-deriving it.

Building from source? Clone the repo, then pnpm install && pnpm check; run the CLI in-tree with pnpm --filter @ui-graph/cli run uigraph -- <command>.

The dashboard on the gauntlet sample: green edges are runtime-witnessed; the coverage panel keeps verified, runtime-verified, and parked honestly distinct

The bundled gauntlet sample after a verify run: 65% of transitions runtime-witnessed (green), 100% accounted — every remaining edge either proven or parked with a written reason.

Multiple projects

map auto-registers each project in ~/.uigraph/; dash/serve without a dir serve them all, switchable in the topbar. The switcher uses opaque ids — absolute paths never leave the server.

Multi-project switcher with the freshness banner and the ranked verify worklist

Freshness is never silent: a stale graph gets a banner, and the verify worklist ranks exactly which conditional edges to confirm next — with the reminder that a confirmation needs proof.

Under the hood

UI-graph layered architecture: consumers, interface layer, model-free core, adapters and the verification loop, the SQLite workspace, and external systems

Three tiers, one invariant — no edge enters the base graph without a deterministic witness:

Tier	Who	What enters the graph
1 — static	ts-morph extractors	route nodes + edges with `file:line` witnesses; anything unresolvable degrades honestly (`may` fan-out, `unknown` sink, soundiness note) — never a silent miss, never a guessed `must`
2 — propose	your agent's LLM	nothing. Proposals are quarantined hypotheses that land on the verify worklist — a wrong proposal costs nothing
3 — verify	Playwright runner / agent	the observation, with evidence attached. Guarded edges keep their guard (one run proves existence, not unconditionality); refuting a static `must` raises the loudest alarm the system has

Extraction quality is enforced by an adversarial gauntlet: a data-router React app packing 25 common-website patterns (examples/sample-gauntlet-react), graded against 35 golden expectations on every pnpm check — a silent miss fails the suite.

Package	Role
`@ui-graph/core`	framework-agnostic IR + pure ops (validate, overlay/merge, diff, plan_path, codegen, coverage, trust tiers)
`@ui-graph/adapter-react`	react-router v5 + v6 + data-router extraction
`@ui-graph/adapter-vue` · `-angular` · `-next`	vue-router, Angular Routes, Next.js App+Pages router
`@ui-graph/mcp`	model-free stdio MCP server, 27 tools
`@ui-graph/cli`	`map` / `verify` / `login` / `dash` / `gen` / `diff` / `serve` / `workspace` / `mcp`
`apps/dashboard`	React Flow viewer: graph, coverage, freshness, verify worklist

Open core

This repository is the complete, MIT-licensed trust engine — nothing epistemic is paywalled. The commercial layer, UI-graph studio (separate private repo), adds the interactive workflow on top: scenario/feature drafting, overlay editing and proposals triage in the UI, and Playwright e2e suite generation from the verified graph. The single-path uigraph gen primitive stays here.

Contributing

Fork and branch.
pnpm install && pnpm check — typecheck + tests + lint must stay green.
Extraction changes must keep the gauntlet at 35/35 (pnpm exec tsx scripts/gauntlet-report.ts); new patterns welcome — add the case and its golden expectation.
Follow the dev cycle in docs/20-development-cycle.md.

Star history

View the star-history chart →

uigraph