cmp-preview
Skill0 starsChanged 47 days agoMITView on GitHub
THE default UI feedback loop while building or editing ANY Compose Multiplatform screen — in a stamped app, use it DURING development, not only when asked: it renders the app's REAL screens headlessly in seconds (no device, no emulator, no manual Gradle) and tells you exactly what each edit changed, so you catch your own mistakes as you build. Use this whenever you are about to write or change CMP/KMP UI code, need quick build/visual feedback, want to verify a UI change landed, or the user asks "preview my app", "show me my screens", "open the preview gallery", "Android Studio previews without the IDE", "see my UI without running the app", "live preview my compose screens", or "storybook for compose". The cmp-inspector MCP's preview service serves a self-updating gallery (pixels, wireframe and a11y per screen) that re-renders on every save — pixels flow to the human, structure flows to the AI.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- template/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- template/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- npm-publishSkill
- plugin-refreshSkill
- cmp-auditSkill
- cmp-dev-clientSkill
- cmp-doctorSkill
- cmp-firebase-connectSkill
- cmp-inspectSkill
- cmp-newSkill
- cmp-qa-prepSkill
- cmp-testSkill
- cmp-upgradeSkill
- grill-meSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Plugin enabled?: Check enabledPlugins in ~/.claude/settings.json (or the project's .claude/settings.json).
- Distinctive: line 33
Plugin copy stale or server broken?: Run cmp-doctor's inspector-MCP check group.
- Very specific: line 35
Only after reporting may the documented degraded path (./gradlew :composeApp:renderScreens
- Very specific: line 68
preview_stop {}: when the session is done (the Gradle daemon stays warm — good). - Very specific: line 123
NOT silent: when a save yields no reload within ~20s the service runs its own compile check, so the compiler's e: lines land in lastError …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
cmp-preview — live previews of real screens, zero commands
Your job: give the human a live gallery URL of their app's real screens and keep it current while they (or you) edit code — and use the structural side of the same render to verify changes. Nobody runs Gradle by hand; the MCP service owns the loop.
Before anything: confirm the capability (fail loud)
The cmp-inspector MCP tools are a capability, not a given. Before your first call, confirm they resolve (ToolSearch for "cmp-inspector"). If no tools match, STOP — do not fall back to manual Gradle, screenshots, or raw adb silently. Diagnose in order and REPORT to the human:
- Plugin enabled? Check
enabledPluginsin~/.claude/settings.json(or the project's.claude/settings.json). - Session older than the plugin's enablement? MCP servers attach at session START — a session born without the plugin never gains its tools, and no amount of in-session retrying will surface them. The fix is restarting the session.
- Plugin copy stale or server broken? Run cmp-doctor's inspector-MCP check group.
Only after reporting may the documented degraded path (./gradlew :composeApp:renderScreens
node qa/preview-gallery.mjs) be used — and the report must name what is lost: on-save re-render, changed-screen attribution, and thepreview_diffchange proof.
The one-call flow
preview { projectDir }(cmp-inspector MCP) — starts (or reuses) the resident service. It:- renders every
inspector/PreviewRegistry.ktentry headlessly via the app's generated:composeApp:renderScreenstask (real Koin DI, real theme, real data); - serves the live gallery at the returned
url(defaulthttp://127.0.0.1:9600/); - watches
composeApp/src/**— every save re-renders (debounced, serialized) and the page reloads itself via SSE, with changed screens flaggedCHANGED. 1b. Phase 2 runs automatically (hot, default true): the service boots a resident preview daemon under Compose Hot Reload (hotRunDesktop --mainClass=<pkg>.inspector.PreviewDaemonKt --auto, JBR auto-provisioned). Saving a file recompiles incrementally and hot-swaps classes INTO the running JVM; renders go through the daemon's loopback/render— measured on a real app: ~900ms for one screen, ~7s for all seven, ~10s save→gallery-shows-the-change (vs 25–40s per change on the task path). If the daemon can't boot (no dev-client feature/hot-reload plugin, no JBR) the service transparently stays on the Gradle path — same gallery, slower loop.
- renders every
- Hand the human the
url(open it for them if you can, e.g.open <url>on macOS, or the host's browser surface). That's their whole workflow: edit → save → watch the gallery update. First render includes a Gradle compile (tens of seconds); warm saves re-render in a few seconds. - You work structurally — after every edit, ONE call:
preview_status { waitForRender: true }. It blocks until the render (or the recompile) finishes and returnschangedLastRender(empty = your edit reached no screen),lastError/lastErrorSource("compile"= your edit didn't even build — the daemon surfaces hot-recompile failures, you are NOT flying blind), andscreens: [{ id, nodes, tokenized, tagged, a11yPass, a11yViolations, lastChangedVersion, tree, png }]. No HTTP polling, no sleeps. Assert deeper on thetreepaths withinspect_tree(passtestTagfor one subtree) — never read PNGs. preview_stop {}when the session is done (the Gradle daemon stays warm — good).
The verified edit loop (with the gallery open)
preview { projectDir }→ human watches the gallery.- Edit code →
preview_status { waitForRender: true }→ the result names the changed screens or carries the compile/render error. preview_diff { screen: <a changed id> }→ a proven verdict (proven-clean/changed-with-regressions/no-change) between the last two renders — the service keeps the previous generation, so there is NO snapshot bookkeeping. The human sees the same change land visually: CHANGED flag, hover-to-compare before/after, and a persistent "changed #N" badge per card.- Baselines that must survive sessions are the lane's golden trees (
qa/golden/, thegoldenTreesstep) — re-bless intended changes withUPDATE_GOLDEN=1.
Single-screen warm renders: render_screen { projectDir, screen } goes through the
running daemon automatically (via: "daemon", ~1s) and falls back to the Gradle task.
State variants (the Storybook "story" analog)
A screen in a forced UI state is just another registry entry with a derived id:
ScreenPreview("home@empty", "Home — empty") { … } hosting the screen with that state
(a state-first overload, or preview-only fakes). Loading/empty/error states then render
side by side with the default seeded state — same gallery, same selectors, same goldens.
The console — three more tabs on the same gallery
The URL from preview { projectDir } is a console, not just a gallery: alongside Screens
(the tab you've been reading about above) it also serves Design System (the swatch/dimen
grid resolved from the app's token catalog), Approvals (every governed artifact — design
system, architecture, exemplar feature/spec, per-feature specs — with its live status and an
Approve button), and Specs (each specs/*.spec.md's clauses with coverage badges). All four
tabs share the same SSE self-reload as the gallery.
Approving in the console (POST /api/approve) writes the exact same qa/approvals.json the
node qa/approve.mjs <artifact> CLI writes — same library underneath, either front end works.
Your side of that loop is approval_status { waitForDecision: true }: identical blocking
pattern to preview_status { waitForRender: true } — propose a change, tell the human to look
at the Approvals tab, then block on the decision instead of polling. Without
waitForDecision it just returns the current snapshot ({available, statuses:[...]}). This is
onboarding territory (the cmp-new skill's final step walks the human through the ordered
approval list); reach for it here whenever a governed artifact changed mid-session and needs
re-review.
Troubleshooting
- "does not look like a create-cmp app" —
projectDirmust containcomposeApp/. - renderScreens task missing — the app predates project previews (scaffolded before
create-cmp 0.6). Re-stamp, or port the harness:
inspector/PreviewRegistry.kt+PreviewHarness.kt+PreviewSemanticsJson.kt(desktopMain) + therenderScreenstask — see the template or the cmp-upgrade skill. - First render slow / red banner "render FAILED" — the banner carries the Gradle error and the gallery keeps the last good state; fix the compile error, save, it recovers on the next cycle.
- Broken edit in daemon mode — a failed hot recompile produces no render, but it is
NOT silent: when a save yields no reload within ~20s the service runs its own compile
check, so the compiler's
e:lines land inlastErrorwithlastErrorSource: "compile", any pendingwaitForRenderresolves with them, and the gallery pill shows "compile failed". Expect that verdict to take ~20–40s (watchdog + compile); a successful edit settles much sooner.lastActivitytells you what the service last saw (src-change / compile-failed / render-ok / render-stale) if you need to distinguish "quiet" from "stuck". - Daemon quirks — the daemon listens on 9601;
preview_stopshuts it down. Rarely, a hot swap can't apply a structural change (Compose Hot Reload limitation) — the daemon keeps serving pre-change renders; restart the preview to heal. DI-module edits (appModules) need a daemon restart too (Koin is started once). - Port busy — the service probes upward from 9600 (or pass
port). Callingpreviewagain for the same project returns the running service's URL unchanged; a differentprojectDirstops the old service first. - Screen missing from the gallery — it's not in
inspector/PreviewRegistry.kt; add aScreenPreviewentry (tab entries are regenerated from--tabsat scaffold time; hand-added screens are yours to register).
Related
- cmp-inspect — the full inspector: tier-1 live device (
connect_live,navigate_and_inspect,/inspect/remoteclick-to-tap device view), token drift, golden trees. cmp-preview is the tier-0 daily driver; reach for cmp-inspect when you need the RUNNING app (real navigation state, on-device data). - cmp-dev-client — the interactive hot-reload desktop window (
hotRunDesktop); complementary: dev-client is one live clickable window, cmp-preview is stills of every screen at once, auto-refreshed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

