Compose Bridge

ComposeBridge 🌉

Real-time on-device visual editor for Jetpack Compose + Model Context Protocol (MCP) server for AI coding agents.
Live UI tuning (<50ms latency), AST-guided surgical source code splicing, and autonomous AI-assisted refactoring.

📰 Featured In

English | العربية

📥 Direct Downloads (v1.1.3)

📸 Visual Demo

Watch ComposeBridge visually edit a running Jetpack Compose UI live:

Screenshots

1. Studio ToolWindow & Token Scanner	2. Surgical Pattern Refactoring & Diff	3. Live On-Device Preview & Inspector

⚡ Quick Start in 60 Seconds

Step 1: Install IDE Plugin

1. Download ComposeBridgeIntelliJ-1.1.5.zip.
2. In Android Studio, go to Settings (Preferences) ➔ Plugins ➔ Click the ⚙️ gear icon ➔ Install Plugin from Disk....
3. Select the zip file and restart Android Studio.

Step 2: Add Dependencies to your Android App

Copy composebridge-runtime-release.aar and composebridge-agent-release.aar into your app module's libs/ folder:

// app/build.gradle.kts
dependencies {
    // 1. Runtime registries: compiles cleanly in both Debug & Release
    implementation(files("libs/composebridge-runtime-release.aar"))

    // 2. Interactive visual inspector: debug builds only
    debugImplementation(files("libs/composebridge-agent-release.aar"))
}

Step 3: Initialize in MainActivity (Debug)

// MainActivity.kt
import com.composebridge.agent.ComposeBridgeAgent

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Start bridge connection (automatically connects to local hub)
        ComposeBridgeAgent.start(serverUrl = "ws://127.0.0.1:8711")

        setContent {
            // Wrap root content in ComposeBridgeAgent.Root
            ComposeBridgeAgent.Root {
                MyApplicationTheme {
                    MainScreen()
                }
            }
        }
    }
}

Step 4: Start the Bridge & Tune Live

1. In Android Studio, open the ComposeBridge tool window on the right sidebar and click ▶ Start Bridge (this starts the local server and runs adb reverse tcp:8711 tcp:8711 automatically).
2. Run your app on your device or emulator.
3. Tap the floating 🔧 FAB on screen to toggle Design Mode.
4. Tap any text, color, or dimension to adjust values in real-time!

📐 Architecture & Communication Flow

ComposeBridge coordinates three interconnected components over a fast local loopback interface:

 +--------------------------+                 +----------------------------+
 |   Android Phone / AVD    |                 |   Local WebSocket Hub      |
 |                          |                 |   (Python 3.10+ Daemon)    |
 |  [App UI in Compose]     |                 |                            |
 |            |             |   WebSocket     |   server.py (:8711)        |
 |  [:composebridge-agent]  |<===============>|      ├── Message Router    |
 |    - Visual Touch Overlay|   (Port 8711)   |      ├── AST Splicer       |
 |    - Semantic Inspector  |                 |      └── PatternJournal    |
 |            |             |                 +----------------------------+
 |  [:composebridge-runtime]|                               ||
 |    - TextRegistry        |                               || JSON-RPC
 |    - ThemeRegistry       |                               || (stdio / TCP)
 |    - DimensionRegistry   |                               \/
 +--------------------------+                 +----------------------------+
                                              |   Developer Tools & AI     |
                                              |                            |
                                              |  [Android Studio Plugin]   |
                                              |    - Live Changes Diff     |
                                              |    - Token Split / Scanner |
                                              |  [Autonomous MCP Agents]   |
                                              |    - Antigravity / Claude  |
                                              |    - 27 Standard MCP Tools |
                                              +----------------------------+

1. On-Device Agent (:composebridge-agent): Injected via ComposeBridgeAgent.Root. Renders non-intrusive hit-testing overlays, extracts semantic metadata, and transmits change requests over local WebSocket (ws://127.0.0.1:8711).
2. Decoupled Runtime (:composebridge-runtime): Standalone ~9KB runtime containing registry singletons (BridgeTextRegistry, BridgeThemeRegistry, BridgeDimensionRegistry). Ensures production Release builds compile with zero overhead without packaging debug overlays.
3. Local Bridge Server (server.py): Acts as the central event hub and Kotlin AST manipulation engine. Applies deterministic changes using file write-locks, atomic rewrites, and maintains a byte-level .bridge.bak rollback journal.
4. Model Context Protocol (MCP Server): Exposes 27 structured tools allowing AI pair programmers (Antigravity, Claude, Cursor) to autonomously analyze token usage, suggest token splits, and execute multi-file refactorings.

🚀 Core Capabilities

🤖 AI Agent Integration (MCP)

ComposeBridge exposes 27 deep-inspection and code refactoring tools to any AI assistant supporting the Model Context Protocol (MCP). No physical phone is required to use MCP tools.

💡 Ultra-Lightweight Context Window: ComposeBridge uses Lazy Loading, so 27 MCP tools consume only ~176 tokens (<1% of context window).

Compatible AI Clients:

• ✅ Google Antigravity IDE
• ✅ Cursor
• ✅ Claude Desktop
• ✅ Windsurf / Continue

Integration Steps:

Step 1: Run the MCP Server

Make sure server dependencies are installed and the server is executable from your server directory:

cd server
pip install -r requirements.txt

Step 2: Configure mcp_config.json

Add the ComposeBridge server configuration to your AI agent's config file (e.g. in ~/.gemini/config/mcp_config.json or your IDE configuration):

{
  "mcpServers": {
    "composebridge": {
      "command": "python",
      "args": ["-u", "C:\Users\thinkpad\StudioProjects\compose-bridge\server\mcp_server.py"],
      "env": {
        "COMPOSEBRIDGE_ROOT": "C:\Users\thinkpad\StudioProjects\MyTeacher-App",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

⚠️ Important: Any changes made to mcp_config.json require starting a New Chat in your AI agent interface so that all 27 MCP tools are freshly discovered and initialized.

How to set it up in Android Studio / Antigravity:

1. Open Android Studio / IntelliJ IDEA.
2. Go to Settings (or Preferences on macOS) → Tools → AI → MCP Servers.
3. Click on the Installed tab.
4. Click on the "Import JSON file" button (or "...Add via JSON" depending on your IDE version).
5. Paste the JSON configuration provided above.
6. Click OK or Apply.
7. ⚠️ Crucial: Start a New Chat (or restart the agent) for the new 27 MCP tools to load and become visible.

Overview of MCP Tools (27 Tools):

• Token Discovery & Analysis: list_tokens, find_token_by_color, get_token_impact, get_token_siblings, get_all_token_groups, list_orphans, get_naming_convention.
• Surgical Code Editing: set_token, set_text, add_token, rollback_last.
• Pattern Refactoring: replace_pattern, list_applied_patterns, rollback_pattern, suggest_token_split, detect_conditional_variants.
• Change Management: list_modified_files, get_file_diff, approve_file_changes, reject_file_changes, approve_all_files, reject_all_files, reject_all_files_force.
• Build Verification & Sync: run_gradle_build, list_allowed_gradle_tasks, trigger_user_sync, get_sync_status.

⚠️ Known Limitations

• Platform Target: Live on-device inspection currently supports Android (API 24+). Kotlin Multiplatform Desktop and iOS overlays are in active development.
• Python Requirement: The local bridge server requires Python 3.10 or newer.
• USB Port Forwarding: When testing on a physical device over USB, port forwarding is required (adb reverse tcp:8711 tcp:8711). The Studio plugin runs this automatically on startup.
• Initial Rebuild on New Tokens: When converting a hardcoded literal to an entirely new named token for the first time, one standard Gradle compile is required so the Kotlin compiler emits the new getter bytecode. Subsequent live tweaks to that token are instantaneous.

🔧 Troubleshooting & FAQ

1. The phone shows [WS] Connection failed

• Ensure the bridge server is running (🟢 Bridge Running in Studio or python server.py in terminal).
• If using USB, verify ADB reverse is active by running:

  adb reverse tcp:8711 tcp:8711
  

• If using Wi-Fi without USB, specify your workstation's LAN IP when calling ComposeBridgeAgent.start(serverUrl = "ws://192.168.1.X:8711").

2. Build error: Duplicate class found in modules

• Make sure composebridge-runtime-release.aar is added under implementation(...) and composebridge-agent-release.aar is added under debugImplementation(...). Do not include the agent in release configurations.

3. Edits do not show in Android Studio

• Ensure you have the project root properly set in composebridge.json or pass --project <path> when launching server.py.
• Check the Changes tab in the ComposeBridge tool window to review pending file diffs.

🤝 Contributing & Community

We welcome contributions! Please review our:

• Contributing Guidelines: Development setup, coding standards, and PR process.
• Security Policy: Supported versions and vulnerability disclosure guidelines.
• Architectural Vision (RFC-001): Technical roadmap and core invariants.

📜 License

Distributed under the Apache License 2.0.