Gradle-first capture for Android and CMP UI loops

Give coding agents eyes for Compose previews.

AgentPreview turns AndroidX @Preview functions into a small bundle of screenshot and JSON artifacts, so AI agents can inspect UI state without opening Android Studio.

Run a capture View source

Early project: use local includeBuild or repository checkout setup until a plugin publication is available.

build/agentPreviewSnapshots

app-main-LoginPreview/android-phone/
  screenshot.png
  snapshot.json

app-main-ProfileCard-previewParam-0/android-phone/
  screenshot.png
  snapshot.json

AndroidX @Preview PreviewParameter Compose semantics layoutTree hints CMP via Android target

What agents receive

A screenshot for vision. JSON for reasoning.

Each capture is designed to be small enough for automated review and specific enough for UI iteration: preview metadata, viewport details, semantics nodes, optional layout-tree data, and best-effort source hints.

Preview-aware

Discovers AndroidX previews, expands @PreviewParameter values, and keeps generated capture IDs filterable.

Agent-readable

Pairs screenshot.png with snapshot.json so an agent can compare pixels with structure.

Source-oriented

Includes source file, line, component, and modifier hints when Compose tooling data makes them available.

Viewport controlled

Capture focused Android phone, tablet, or custom viewports without running a full visual test suite.

snapshot.json

{
  "schemaVersion": 2,
  "preview": {
    "id": ":app:main:LoginPreview:previewParam-0",
    "name": "Login",
    "group": "Auth",
    "source": "LoginPreview.kt:12",
    "previewParameter": {
      "providerClassName": "dev.example.LoginStateProvider",
      "index": 0
    }
  },
  "viewport": {
    "platform": "android",
    "name": "phone",
    "width": 393,
    "height": 852,
    "density": 1.0
  },
  "nodes": [{
    "id": "semantics-12",
    "role": "button",
    "text": "Continue",
    "bounds": { "x": 48, "y": 720, "width": 297, "height": 56 },
    "source": "LoginScreen.kt:84"
  }],
  "layoutTree": [{
    "id": "layout-3",
    "boundsPx": { "x": 24, "y": 96, "width": 345, "height": 640 },
    "boundsDp": { "x": 24.0, "y": 96.0, "width": 345.0, "height": 640.0 },
    "componentHint": "androidx.compose.foundation.layout.Column",
    "sourceName": "LoginCard",
    "sourceFile": "LoginScreen.kt",
    "sourceLine": 84,
    "sourceHintKind": "tooling-nearest-app-ancestor"
  }],
  "render": { "mode": "robolectric" }
}

Focused by default

Use Gradle commands agents already know how to run.

AgentPreview stays close to the build. List previews, dry-run a plan, narrow by preview or viewport, then capture only the UI states that matter for the current change.

Wire the local plugin

// settings.gradle.kts
pluginManagement {
  includeBuild("../AgentPreview")
}

Apply and configure

plugins {
  id("dev.staticvar.agentpreview")
}

agentPreview {
  maxPreviewParameterValues.set(8)
  android {
    viewport("phone", 393, 852)
  }
}

List and plan

./gradlew :app:listComposePreviews

./gradlew :app:captureComposePreviews \
  -PagentPreview.dryRun=true \
  -PagentPreview.previewNameFilter=Login

Capture the target states

./gradlew :app:captureComposePreviews \
  -PagentPreview.previewNameFilter=Login,ProfileCard:previewParam-0 \
  -PagentPreview.viewportFilter=phone \
  -PagentPreview.maxCaptures=4 \
  -PagentPreview.maxParallelRenders=2

Built for agent iteration

Android apps first. CMP through the Android target.

The initial backend is Android-focused and uses the Android target for Compose Multiplatform projects. That keeps captures aligned with existing Gradle builds while leaving room for future platform-specific renderers.

Works with AndroidX @Preview annotations and preview metadata.
Expands PreviewParameter providers with configurable caps.
Exports semantics nodes for accessible text, roles, actions, tags, and bounds.
Adds layout tree and source hints when render-time tooling data can be correlated.

Honest boundaries

What AgentPreview does not promise yet.

Android backend first

Current captures are designed around Android rendering. Desktop and web Compose renderers are future work.

CMP via Android

Compose Multiplatform support is routed through the Android target, not native desktop or web targets.

Hints are best-effort

Layout and source hints depend on Compose tooling data and may fall back to framework or preview-entrypoint information.

Publication pending

Until the plugin is published, examples should use a local checkout with includeBuild or equivalent repository wiring.

Let agents inspect the UI they are changing.

Start with a local checkout, capture one preview, and hand the screenshot plus JSON bundle to your coding agent.

Open AgentPreview on GitHub