{"id":49999736,"url":"https://github.com/beyondwin/fixthis","last_synced_at":"2026-07-05T07:00:22.740Z","repository":{"id":356240978,"uuid":"1231321364","full_name":"beyondwin/FixThis","owner":"beyondwin","description":"Point at any Jetpack Compose UI element, annotate it, and hand off source pinned prompts to AI coding agents. Local only, debug only, MCP native.","archived":false,"fork":false,"pushed_at":"2026-07-01T08:43:16.000Z","size":15971,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T10:26:33.776Z","etag":null,"topics":["android","android-mcp","android-tools","developer-tools","jetpack-compose","mcp"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beyondwin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-06T21:12:06.000Z","updated_at":"2026-07-01T08:43:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beyondwin/FixThis","commit_stats":null,"previous_names":["beyondwin/fixthis"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/beyondwin/FixThis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondwin%2FFixThis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondwin%2FFixThis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondwin%2FFixThis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondwin%2FFixThis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beyondwin","download_url":"https://codeload.github.com/beyondwin/FixThis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondwin%2FFixThis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35145900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-mcp","android-tools","developer-tools","jetpack-compose","mcp"],"created_at":"2026-05-19T10:00:37.750Z","updated_at":"2026-07-05T07:00:22.601Z","avatar_url":"https://github.com/beyondwin.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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- 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.4.1\n\nfixthis install-agent --project-dir . --target all --verify --json\n```\n\nIf Homebrew already has FixThis installed, run\n`brew update \u0026\u0026 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.4.1\"\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 \u003cthis-repo\u003e \u0026\u0026 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:\u003cport\u003e`.\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- **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 may still contain sensitive pixels. Review copied prompts or local\nartifacts before sharing them outside your machine, and do not commit\n`.fixthis/`.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondwin%2Ffixthis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeyondwin%2Ffixthis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondwin%2Ffixthis/lists"}