FixThis
Local-first MCP handoff for Jetpack Compose UI feedback and source candidates.
FixThis for Android Compose
Point at a Jetpack Compose UI, write the change, and hand Claude, Codex, Cursor, or another coding agent the source context it needs.
FixThis is debug-only. It attaches a sidekick to a Compose debug app, mirrors the screen into a local browser console, and turns annotations into a compact handoff: screenshot bounds, semantics, source candidates, and confidence warnings.
Click a component to select it. Drag when the target is spacing, empty room, or something that is not a clean Compose node.
Works Today
- Try the sample app in about five minutes.
- Install the desktop CLI/MCP with Homebrew, npm, or GitHub Releases.
- Add it to an external app with the Gradle plugin
io.github.beyondwin.fixthis.compose. - Let Claude Code or Codex configure the sample with
./scripts/bootstrap-mcp.sh --sample. - Let an agent configure your app with
fixthis install-agent. - Use Copy Prompt with Cursor, ChatGPT, or any chat agent.
- Use Save to MCP with Claude Code or Codex.
- Save to MCP can attach a bounded, redacted Android diagnostics baseline. Switch the session to Manual or Off if you do not want that. Copy Prompt never starts collection.
- Runs locally over ADB and
127.0.0.1. No external API calls.
Quick Start: Agent Installs FixThis in Your App
Claude Code / Codex Bootstrap Prompt
Paste this 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
brew install beyondwin/tools/fixthis
# Node
npm install -g @beyondwin/fixthis
# macOS/Linux fallback
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 it, run
brew update && brew upgrade beyondwin/tools/fixthis and check
fixthis --version.
fixthis install-agent applies the Gradle plugin, writes MCP config, and
writes .fixthis/project.json plus .fixthis/agent-setup.*. If doctor
reports NEEDS_INSTALL or metadata is missing, run ./gradlew fixthisSetup
and rerun fixthis install-agent --project-dir . --target all --verify --json.
Restart Claude Code or Codex when the report asks, then call
fixthis_open_feedback_console. For a manual check, use
fixthis doctor --project-dir . --json.
Published plugin:
plugins {
id("io.github.beyondwin.fixthis.compose") version "1.5.0"
}
The plugin adds the debug-only sidekick and keeps release builds out.
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, and opens FixThis
Studio at http://127.0.0.1:<port>.
In the console:
- Click Annotate.
- Click a UI element, or drag an area.
- Type the change you want.
- Repeat for other spots on this screen.
- Copy Prompt for a chat agent, or Save to MCP for Claude Code / Codex.
You are done when a numbered annotation is visible and you have copied Markdown or saved a local MCP handoff.
Maintainers can prove that Copy Prompt path on a connected device:
npm run real-copy-prompt:smoke -- --strict
Pick Your Path
| Goal | Start here |
|---|---|
| Try it without touching your app | Sample quick start |
| Add it to your debug build | Add to your app |
| Connect an agent | Connect your agent |
| Bootstrap MCP from this repo | MCP.md |
| Use the console | Console tour |
| Understand the product | Product |
| Diagnose a failure | Troubleshooting |
| Inspect contracts | Docs index |
| Contribute | CONTRIBUTING.md |
| Reader | Start here |
|---|---|
| First-time user | Sample quick start |
| External app developer | Add to your app |
| Agent in this repo | AGENTS.md and project map |
| Maintainer | Docs index and project map |
| Contract or CLI change | Reference contracts |
Why not just a screenshot?
A screenshot is enough when the target is obvious. FixThis helps when the UI is dense, list-rendered, or named mostly by composable:
- Top-3 source candidates with line numbers and match reasons
editSurfacehints for call site vs component vs copy vs layout vs interop- Instance grouping so identical cards stay distinct
- Screen fingerprint so a rotated or changed screen cannot sneak into a save
- Honest confidence: visual-only, stale, or possible AndroidView/WebView
- Bounded runtime diagnostics on Save to MCP
- Retry-safe batches that do not duplicate work
Modules
| Module | Role |
|---|---|
:app (sample/) | Validation sample |
:fixthis-compose-core | Pure Kotlin domain |
:fixthis-compose-sidekick | Debug Android runtime |
:fixthis-gradle-plugin | Source index and debug wiring |
:fixthis-cli | Desktop CLI |
:fixthis-mcp | MCP server and local console |
More: Product, decisions, architecture.
Status
Public install paths:
- Gradle plugin
io.github.beyondwin.fixthis.compose - Maven
io.github.beyondwin:fixthis-compose-sidekickandfixthis-compose-core - Homebrew
brew install beyondwin/tools/fixthis - GitHub Release
fixthis-cli-mcp-vX.Y.Z.tar.gz - npm
@beyondwin/fixthis - MCP Registry
io.github.beyondwin/fixthis
Live dashboard: Release readiness.
main may be ahead of the latest tag. See CHANGELOG
and release notes.
Agents in this repo should read AGENTS.md.
Trust
FixThis stays on your machine. The sidekick talks over ADB, the console binds
to localhost, and Save to MCP writes under .fixthis/. Screenshots can
still contain sensitive pixels. Review them before sharing. Do not commit
.fixthis/.
Details: Privacy, Security, Threat model.
V1 stays narrow: Compose debug builds, local ADB, MCP-first handoff, best-effort source candidates, no cloud upload. See Roadmap.
License
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @beyondwin/fixthisSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-beyondwin-fixthis": {
"command": "npx",
"args": [
"-y",
"@beyondwin/fixthis"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
@beyondwin/fixthisnpmCompatible MCP Clients
FixThis works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.