FixThis for Android Compose

Point at a Jetpack Compose UI, write the change you want, and hand Claude, Codex, Cursor, or another coding agent the source context it needs.

FixThis adds a debug-only sidekick to a Compose app, mirrors the current screen into a local browser console, and turns your UI annotations into a compact agent handoff with screenshot bounds, semantics context, source candidates, and target-confidence warnings.

In the browser console, a single click selects the nearest Compose UI component, and a drag selects any visual area when the target is spacing, empty room, interop content, or another region that is not a clean component.

Works Today

• Try the bundled sample app in about five minutes.
• Install the published desktop CLI/MCP package with Homebrew on macOS or from npm / GitHub Releases on macOS/Linux.
• Add FixThis to an external Android app with the published Gradle plugin: io.github.beyondwin.fixthis.compose.
• Let Claude Code or Codex configure the sample MCP server with ./scripts/bootstrap-mcp.sh --sample.
• Let an agent configure your Android app with fixthis install-agent.
• Use Copy Prompt with Cursor, ChatGPT, or any chat-style coding agent.
• Use Save to MCP with Claude Code or Codex after running the bootstrap script.
• Let Save to MCP collect a bounded, redacted Android diagnostics baseline for new sessions; switch the session to Manual or Off when automatic collection is not appropriate. Copy Prompt never starts collection.
• Runs locally over ADB and 127.0.0.1; FixThis makes no external API calls.
• Debug builds only. Jetpack Compose only.

Quick Start: Agent Installs FixThis in Your App

Claude Code / Codex Bootstrap Prompt

FixThis is debug-only and Jetpack Compose only. Paste this prompt into Claude Code or Codex from the root of a Jetpack Compose Android app:

Install FixThis in this project and configure it for this agent.

Use this order:
1. Run `fixthis install-agent --project-dir . --target all --verify --json`.
2. Use the JSON `readiness.state` and `actions[]` as the source of truth.
3. If `requiresUserAction` is true, tell me the exact blocking action.
4. Do not call `fixthis_open_feedback_console` until `readyForMcpTooling` is true, or until the report's `agent_after_restart` action is reached after restart.

Restart Claude Code or Codex if the report asks for it.
Do not configure release builds. Do not commit `.fixthis/`.

The agent should run:

# macOS package-manager path
brew install beyondwin/tools/fixthis

# Node/npm path
npm install -g @beyondwin/fixthis

# macOS/Linux fallback path
curl -fsSL https://raw.githubusercontent.com/beyondwin/FixThis/main/scripts/install-fixthis.sh \
  | bash -s -- --version v1.5.0

fixthis install-agent --project-dir . --target all --verify --json

If Homebrew already has FixThis installed, run brew update && brew upgrade beyondwin/tools/fixthis and verify the active binary with fixthis --version.

fixthis install-agent patches the detected Android app module with the published Gradle plugin, writes MCP config for Claude Code / Codex, writes .fixthis/project.json, and writes .fixthis/agent-setup.* handoff files. If doctor reports NEEDS_INSTALL or generated metadata is missing, run ./gradlew fixthisSetup as a recovery step and rerun fixthis install-agent --project-dir . --target all --verify --json. Restart Claude Code or Codex when the report asks for it, then call fixthis_open_feedback_console. For manual diagnostics, the same setup can be checked with fixthis doctor --project-dir . --json.

The published Gradle plugin coordinates:

plugins {
    id("io.github.beyondwin.fixthis.compose") version "1.5.0"
}

The plugin adds the debug-only sidekick dependency automatically, generates FixThis project metadata, and keeps release builds out of scope.

Quick Start: Sample App to Agent Handoff

git clone <this-repo> && cd FixThis
./gradlew :fixthis-cli:installDist :fixthis-mcp:installDist
fixthis-cli/build/install/fixthis/bin/fixthis doctor --package io.github.beyondwin.fixthis.sample
fixthis-cli/build/install/fixthis/bin/fixthis run --package io.github.beyondwin.fixthis.sample

fixthis run installs the sample debug APK, launches it, attaches the sidekick bridge, and opens FixThis Studio at http://127.0.0.1:<port>.

In the console:

1. Click Annotate.
2. Click a Compose UI element, or drag a visual area.
3. Type the requested change in the annotation detail.
4. Repeat click/drag for any other changes on this screen.
5. Click Copy Prompt for any chat-style agent, or Save to MCP for Claude Code / Codex.

You are done when the console shows a numbered annotation and you have either copied compact Markdown or saved a local MCP handoff.

Maintainers can validate that same real Copy Prompt path across the runtime fixtures with a connected emulator or device:

npm run real-copy-prompt:smoke -- --strict

Pick Your Path

How to Read the Docs

Why FixThis vs. just sending a screenshot?

Modern coding agents already accept screenshots and accessibility trees. FixThis adds the missing handoff structure:

• Pin to source, not pixels. Top-3 ranked source-file candidates with line numbers, match reasons, and a margin score — the agent edits the right call site instead of guessing which composable rendered which pixel.
• Route visual edits to the likely surface. editSurface hints carry role tokens for call sites, component definitions, copy/data, layout/style, visual-area work, and interop risk, so a style request is not forced through the same path as a text-source match.
• Stable target identity. Instance grouping (instance i/N), duplicate-marker detection, and overlap-group hints keep N visually identical cards distinguishable.
• Screen integrity checks. Frozen previews carry a screen fingerprint; if the app rotates, changes window mode, or otherwise moves to a different screen before saving, FixThis asks you to re-capture, force-save, or cancel.
• Honest target confidence. Handoffs can mark visual-only, stale, or possible AndroidView/WebView targets so agents know when to verify rather than trust source hints directly.
• Agent verification posture. Handoffs say whether the agent should inspect source first, corroborate multiple signals, treat source paths as hints, or verify manually.
• Bounded runtime diagnostics. Save to MCP can attach redacted summaries from fixed baseline, logs, memory, and performance presets while raw artifacts stay in quota-limited local bundles under .fixthis/.
• Retry-safe local batches. Slow or retried Copy Prompt / Save to MCP saves reuse browser draft ids, so duplicate requests do not create duplicate agent work.
• Batched, structured handoff. One prompt can carry many annotations across many screens, each with its own bounds, severity, and source pin.

If your screen has a single obvious target with clear text, a plain screenshot may already be enough. FixThis pays off when the UI is dense, list-rendered, or labeled mostly by composable name.

Module Map