{
  "markdown": "# FixThis for Android Compose\n\n[![CI](https://github.com/beyondwin/FixThis/actions/workflows/ci.yml/badge.svg)](https://github.com/beyondwin/FixThis/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![JDK 21](https://img.shields.io/badge/JDK-21-orange.svg)](https://adoptium.net/)\n[![Node 20+](https://img.shields.io/badge/Node-20%2B-339933.svg)](https://nodejs.org/)\n[![Compose](https://img.shields.io/badge/Jetpack_Compose-2025.01.01-4285F4.svg)](https://developer.android.com/jetpack/compose)\n\n![FixThis Studio — point at any Jetpack Compose UI element, annotate, hand off AI-ready context to your coding agent](docs/assets/fixthis-studio-hero.png)\n\nPoint at a Jetpack Compose UI, write the change you want, and hand Claude,\nCodex, Cursor, or another coding agent the source context it needs.\n\nFixThis adds a debug-only sidekick to a Compose app, mirrors the current screen\ninto a local browser console, and turns your UI annotations into a compact\nagent handoff with screenshot bounds, semantics context, source candidates, and\ntarget-confidence warnings.\n\nIn the browser console, a single click selects the nearest Compose UI\ncomponent, and a drag selects any visual area when the target is spacing, empty\nroom, interop content, or another region that is not a clean component.\n\n## Works Today\n\n- Try the bundled sample app in about five minutes.\n- Install the published desktop CLI/MCP package with Homebrew on macOS or from\n  npm / GitHub Releases on macOS/Linux.\n- Add FixThis to an external Android app with the published Gradle plugin:\n  `io.github.beyondwin.fixthis.compose`.\n- Let Claude Code or Codex configure the sample MCP server with `./scripts/bootstrap-mcp.sh --sample`.\n- Let an agent configure your Android app with `fixthis install-agent`.\n- Use **Copy Prompt** with Cursor, ChatGPT, or any chat-style coding agent.\n- Use **Save to MCP** with Claude Code or Codex after running the bootstrap script.\n- Let **Save to MCP** collect a bounded, redacted Android diagnostics baseline\n  for new sessions; switch the session to Manual or Off when automatic\n  collection is not appropriate. **Copy Prompt** never starts collection.\n- Runs locally over ADB and `127.0.0.1`; FixThis makes no external API calls.\n- Debug builds only. Jetpack Compose only.\n\n## Quick Start: Agent Installs FixThis in Your App\n\n### Claude Code / Codex Bootstrap Prompt\n\nFixThis is debug-only and Jetpack Compose only. Paste this prompt into Claude\nCode or Codex from the root of a Jetpack Compose Android app:\n\n```text\nInstall FixThis in this project and configure it for this agent.\n\nUse this order:\n1. Run `fixthis install-agent --project-dir . --target all --verify --json`.\n2. Use the JSON `readiness.state` and `actions[]` as the source of truth.\n3. If `requiresUserAction` is true, tell me the exact blocking action.\n4. Do not call `fixthis_open_feedback_console` until `readyForMcpTooling` is true, or until the report's `agent_after_restart` action is reached after restart.\n\nRestart Claude Code or Codex if the report asks for it.\nDo not configure release builds. Do not commit `.fixthis/`.\n```\n\nThe agent should run:\n\n```bash\n# macOS package-manager path\nbrew install beyondwin/tools/fixthis\n\n# Node/npm path\nnpm install -g @beyondwin/fixthis\n\n# macOS/Linux fallback path\ncurl -fsSL https://raw.githubusercontent.com/beyondwin/FixThis/main/scripts/install-fixthis.sh \\\n  | bash -s -- --version v1.5.0\n\nfixthis install-agent --project-dir . --target all --verify --json\n```\n\nIf Homebrew already has FixThis installed, run\n`brew update && brew upgrade beyondwin/tools/fixthis` and verify the active\nbinary with `fixthis --version`.\n\n`fixthis install-agent` patches the detected Android app module with the\npublished Gradle plugin, writes MCP config for Claude Code / Codex, writes\n`.fixthis/project.json`, and writes `.fixthis/agent-setup.*` handoff files.\nIf doctor reports `NEEDS_INSTALL` or generated metadata is missing, run\n`./gradlew fixthisSetup` as a recovery step and rerun\n`fixthis install-agent --project-dir . --target all --verify --json`. Restart\nClaude Code or Codex when the report asks for it, then call\n`fixthis_open_feedback_console`.\nFor manual diagnostics, the same setup can be checked with\n`fixthis doctor --project-dir . --json`.\n\nThe published Gradle plugin coordinates:\n\n```kotlin\nplugins {\n    id(\"io.github.beyondwin.fixthis.compose\") version \"1.5.0\"\n}\n```\n\nThe plugin adds the debug-only sidekick dependency automatically, generates\nFixThis project metadata, and keeps release builds out of scope.\n\n## Quick Start: Sample App to Agent Handoff\n\n```bash\ngit clone <this-repo> && cd FixThis\n./gradlew :fixthis-cli:installDist :fixthis-mcp:installDist\nfixthis-cli/build/install/fixthis/bin/fixthis doctor --package io.github.beyondwin.fixthis.sample\nfixthis-cli/build/install/fixthis/bin/fixthis run --package io.github.beyondwin.fixthis.sample\n```\n\n`fixthis run` installs the sample debug APK, launches it, attaches the\nsidekick bridge, and opens FixThis Studio at `http://127.0.0.1:<port>`.\n\nIn the console:\n\n1. Click **Annotate**.\n2. Click a Compose UI element, or drag a visual area.\n3. Type the requested change in the annotation detail.\n4. Repeat click/drag for any other changes on this screen.\n5. Click **Copy Prompt** for any chat-style agent, or **Save to MCP** for\n   Claude Code / Codex.\n\nYou are done when the console shows a numbered annotation and you have either\ncopied compact Markdown or saved a local MCP handoff.\n\nMaintainers can validate that same real Copy Prompt path across the runtime\nfixtures with a connected emulator or device:\n\n```bash\nnpm run real-copy-prompt:smoke -- --strict\n```\n\n## Pick Your Path\n\n| Goal | Start here |\n| --- | --- |\n| Try FixThis without touching your app | [Quick Start with the sample](docs/getting-started/try-the-sample.md) |\n| Add FixThis to your Compose debug build | [Add FixThis to your app](docs/getting-started/add-to-your-app.md) |\n| Connect Claude Code, Codex, Cursor, or a chat agent | [Connect your agent](docs/getting-started/connect-your-agent.md) |\n| Let an agent bootstrap MCP from the repo | [MCP bootstrap](MCP.md) |\n| Learn the browser console workflow | [Feedback console tour](docs/guides/feedback-console-tour.md) |\n| Understand the product concept and handoff rationale | [Concept and handoff rationale](docs/product/concept-and-handoff-rationale.md) |\n| Diagnose setup problems | [Troubleshooting](docs/guides/troubleshooting.md) |\n| Inspect CLI, MCP, or JSON contracts | [Documentation index](docs/index.md) |\n| Contribute | [Contributing guide](CONTRIBUTING.md) |\n\n## How to Read the Docs\n\n| Reader | Start Here | Why |\n| --- | --- | --- |\n| First-time user | [Quick Start with the sample](docs/getting-started/try-the-sample.md) | Creates one real handoff before touching your app. |\n| External app developer | [Add FixThis to your app](docs/getting-started/add-to-your-app.md) | Covers Gradle wiring, agent setup, and done-state checks. |\n| Coding agent in this repo | [AGENTS.md](AGENTS.md) and [Project map](docs/guides/project-map.md) | Gives read order, source-of-truth priority, module boundaries, and artifact rules. |\n| Maintainer | [Documentation index](docs/index.md) and [Project map](docs/guides/project-map.md) | Routes architecture, reference contracts, validation, and release docs. |\n| Contract or CLI change | [Reference docs](docs/index.md#reference-contracts) | Stable CLI, MCP, bridge, output schema, and compatibility surfaces live there. |\n\n## Why FixThis vs. just sending a screenshot?\n\nModern coding agents already accept screenshots and accessibility trees.\nFixThis adds the missing handoff structure:\n\n- **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.\n- **Route visual edits to the likely surface.** `editSurface` hints carry role\n  tokens for call sites, component definitions, copy/data, layout/style,\n  visual-area work, and interop risk, so a style request is not forced through\n  the same path as a text-source match.\n- **Stable target identity.** Instance grouping (`instance i/N`), duplicate-marker detection, and overlap-group hints keep N visually identical cards distinguishable.\n- **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.\n- **Honest target confidence.** Handoffs can mark visual-only, stale, or\n  possible AndroidView/WebView targets so agents know when to verify rather\n  than trust source hints directly.\n- **Agent verification posture.** Handoffs say whether the agent should inspect source first, corroborate multiple signals, treat source paths as hints, or verify manually.\n- **Bounded runtime diagnostics.** Save to MCP can attach redacted summaries\n  from fixed `baseline`, `logs`, `memory`, and `performance` presets while raw\n  artifacts stay in quota-limited local bundles under `.fixthis/`.\n- **Retry-safe local batches.** Slow or retried `Copy Prompt` / `Save to MCP`\n  saves reuse browser draft ids, so duplicate requests do not create duplicate\n  agent work.\n- **Batched, structured handoff.** One prompt can carry many annotations across many screens, each with its own bounds, severity, and source pin.\n\nIf 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.\n\n## Module Map\n\n| Module | Role |\n| --- | --- |\n| `:app` (`sample/`) | Validation sample app |\n| `:fixthis-compose-core` | Pure Kotlin domain |\n| `:fixthis-compose-sidekick` | Debug Android runtime |\n| `:fixthis-gradle-plugin` | Source-index generation and debug DI |\n| `:fixthis-cli` | Desktop CLI |\n| `:fixthis-mcp` | stdio MCP server and local HTTP feedback console |\n\nProduct and architecture details live in\n[Concept and handoff rationale](docs/product/concept-and-handoff-rationale.md),\n[Product concept](docs/product/README.md),\n[Decision rationale](docs/product/decision-rationale.md), and\n[Architecture overview](docs/architecture/overview.md).\n\n## Status\n\nFixThis has public artifacts for the agent-first path:\n\n- Gradle plugin: `io.github.beyondwin.fixthis.compose`\n- Maven artifacts: `io.github.beyondwin:fixthis-compose-sidekick` and\n  `io.github.beyondwin:fixthis-compose-core`\n- Homebrew tap: `brew install beyondwin/tools/fixthis`\n- CLI/MCP package: GitHub Release asset `fixthis-cli-mcp-vX.Y.Z.tar.gz`\n- npm wrapper: `npm install -g @beyondwin/fixthis`\n- MCP Registry entry: `io.github.beyondwin/fixthis`\n\nThe live release dashboard is\n[Release readiness](docs/contributing/release-readiness.md). It lists current\ncoordinates, verification commands, and registry follow-ups.\n\nCurrent `main` may contain changes after the latest tag. See\n[`CHANGELOG.md`](CHANGELOG.md#unreleased) and\n[release notes](docs/releases/README.md) before cutting another release.\n\nAgents working inside this repository should also read [AGENTS.md](AGENTS.md).\n\n## Trust and Privacy\n\nFixThis is local-first: the sidekick talks to the desktop tools over ADB, the\nbrowser console binds to localhost, and **Save to MCP** writes local files under\n`.fixthis/`. FixThis does not call an external AI API.\n\nScreenshots and runtime diagnostics may still contain sensitive pixels or app\ndata. Review copied prompts and local artifacts before sharing them outside\nyour machine, and do not commit `.fixthis/`. Runtime evidence is redacted and\nbounded, but it remains local debug data that you control.\n\nDetails: [Privacy](docs/reference/privacy.md), [Security](SECURITY.md), and\n[Threat model](docs/reference/threat-model.md).\n\n## Roadmap\n\nFixThis V1 stays intentionally narrow: Jetpack Compose debug builds, local ADB\ntransport, MCP-first handoff, best-effort source candidates, and no cloud\nupload.\n\nThe detailed roadmap lives in [Roadmap](docs/product/roadmap.md). It covers V1\nscope, public artifact release work, deeper interop awareness, SSE-driven\nconsole state sync, smarter source matching, and future agent integrations.\n\n## License\n\n[MIT License](LICENSE). See also [`NOTICE`](NOTICE) for third-party attribution.\n",
  "bytes": 12372,
  "sha": "449944203e29c24fa87a824586cbcdce31f732dbe6c24f267243e56ea425ca00",
  "repo_slug": "beyondwin/fixthis",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_beyondwin_fixthis_086f967d/readme"
}