ComposeBridge 🌉

Real-time on-device visual editor for Jetpack Compose.
Live UI tuning + schema-driven screen compiler + AST-guided source splicing.

📰 Featured In

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.

🎬 See it in action

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

🚀 Key Features

📦 Repository Structure

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

✅ Compatibility

🛠️ Quick Start

1. Start the local server

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

2. Generate a Compose project

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

3. Open in Android Studio

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.

🤔 Why not just wait for Compose Hot Reload?

⚡ Performance

Runtime tuning and disk persistence are fully decoupled.

🧠 Under the Hood

• 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.

🤖 MCP Server (AI Agents)

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

🆕 v0.4.0 — MCP works independently of the phone

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.

Two Operation Modes

Supported Clients

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

Setup

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

Available Tools

Example

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.

Persistent Journal

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

Why Standalone MCP Matters

• 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.

🔒 Security

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

⚠️ Limitations

• 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.

🤖 Coming Soon

• 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.

🔎 Search Terms This Project Solves

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

📜 License

Distributed under the Apache License 2.0.