ComposeBridge 🌉

Real-time on-device visual editor for Jetpack Compose + MCP Server for AI agents. Live UI tuning, AST-guided surgical source splicing, and standalone AI-driven code edits — no phone needed..

English | العربية

ComposeBridge is a developer tooling suite that bridges a running Android app on a physical device with your IDE over a local WebSocket. You can:

• 🎯 Tap any Composable on the phone to inspect it in real time
• 🎨 Tune colors, dimensions, and paddings live at 60fps — no Gradle build required
• 💾 Persist tweaks to your Kotlin source (AppDimens.kt, AppColors.kt) via a surgical byte-splice that preserves file formatting
• 🧩 Generate full Compose screens from a declarative JSON schema
• 🔍 Navigate the runtime tree — tap a parent, drill into children

Live preview is truly zero-rebuild. Persisting the change into the final APK artifact still requires one standard rebuild, after which the new value becomes the source of truth.

Click the preview below to watch ComposeBridge visually edit a running Jetpack Compose UI and persist the change back to Kotlin source.

composebridge/
├── cli/         # JSON → Compose screen compiler
├── agent/       # Android runtime library (:composebridge-agent)
├── server/      # Python WebSocket daemon + source byte-splicer
├── examples/    # Complete reference app (StudentApp)
└── docs/        # Architecture + setup guides

Three components, one workflow:

1. CLI — generates a full project from JSON
2. Agent — captures touches and pushes live updates on the device
3. Server — coordinates messages + writes changes back to .kt files

cd server
pip install -r requirements.txt
python server.py

cd cli
python generate.py screens/dashboard.json

The CLI will produce a full Android project under output/ — including:

• ✅ Theme files (AppColors.kt, AppDimens.kt, AppTypography.kt, AppStrings.kt)
• ✅ UI components (HeroCard, StatCard, DashboardHeader, ...)
• ✅ The full DashboardPage.kt
• ✅ The composebridge-agent module
• ✅ The bridge/ Python server, wired to the new project's path
• ✅ MainActivity.kt with the agent already wired up
• ✅ AndroidManifest.xml with INTERNET permission

Open the generated project, deploy it to a physical device, then:

adb reverse tcp:8711 tcp:8711

Tap the 🔧 floating button → Design Mode ON. Tap any element → the panel opens → slide/tap to tune live.

Runtime tuning and disk persistence are fully decoupled.

• Bidirectional runtime-to-source mapping — every visual change is traceable to its exact Kotlin byte range.
• AST-guided inspection and byte-splice editing — Tree-sitter locates the exact edit site; regex and byte replacement update the file without disturbing formatting.
• Deterministic layout compilation — the CLI emits structured, tokenized Compose code with stable output.
• Low-latency WebSocket daemon — sub-50ms round-trip between the device and the local editing server.

ComposeBridge exposes its tools to AI agents via the Model Context Protocol (MCP).

Important: As of v0.4.0, the MCP Server operates standalone — it does not require the phone, the WebSocket bridge, or adb reverse.

Use it directly from Antigravity IDE, Claude Desktop, or any MCP-compatible client to edit your Compose project files.

• ✅ Antigravity IDE (Gemini)
• ✅ Claude Desktop
• ✅ Cursor
• ✅ Cline / Continue

1. Install dependencies

cd server
pip install -r requirements.txt

2. Configure your AI client

Antigravity IDE — edit ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "composebridge": {
      "command": "python",
      "args": ["C:\path\to\composebridge-en\server\mcp_server.py"]
    }
  }
}

Claude Desktop — edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "composebridge": {
      "command": "python",
      "args": ["C:\path\to\composebridge-en\server\mcp_server.py"]
    }
  }
}

3. Restart your AI client

In Antigravity chat:

@composebridge set_token("welcomeCardHeight", "300")

Result in AppDimens.kt:

- val welcomeCardHeight: Dp get() = BridgeDimensionRegistry.get("welcomeCardHeight", 240.dp)
+ val welcomeCardHeight: Dp get() = BridgeDimensionRegistry.get("welcomeCardHeight", 300.dp)

= Single-line git diff. No phone required.

Every edit is journaled to .composebridge-journal.json. If your AI client crashes or restarts, rollback_last still works.

• No need to build & deploy the app to edit code
• AI can work on Compose projects during design phase
• Fully local — no network, no telemetry

⚠️ Status: v0.4.0-alpha — under active development.

• Debug Builds Only: Agent bundled with debugImplementation
• Token Authentication: WebSocket requires token on handshake
  • ⚠️ v0.4.0 uses a fixed local token. QR-based pairing planned for v0.5.0.
• Journal Rollback: Auto-rollback on AST validation failure

• AST Validation: Surgical edits are restricted to simple literal values (integer_literal, float_literal, string_literal, simple_identifier, long_literal) to prevent parser syntax corruption.
• Correspondence: ~70% on production apps (inline composables may misalign). Compose Compiler plugin is on the roadmap.
• UTF-16/UTF-8: Edge cases with emoji-heavy files are still being handled. Full precision on the roadmap.
• Generated Code: Files from KSP/Kapt may need manual exclusion today. Auto-detection is on the roadmap.

• AI-Powered Suggestions (Qwen integration) — describe a change in natural language; the tool finds the right token and applies it.
• Natural Language Editing — "Make this card taller." "Use the gold accent here."
• MCP Server — expose ComposeBridge as a tool for Claude Desktop, Cursor, and other AI agents.
• More component templates — e-commerce, forms, profile screens.
• Typography tokens — full typography token live editing.

If you've searched for any of these, this project is for you:

• Jetpack Compose edit without recompile
• Compose hot reload alternative
• Interactive layout inspector for Android
• Live UI tweaking on a real Android device
• Sync design tokens to Kotlin source
• Generate Compose UI from a JSON schema

Distributed under the Apache License 2.0.