Rebound helps Android and Compose Multiplatform teams catch recomposition regressions before they ship.

It instruments every @Composable function, applies a budget based on what that composable does, and flags the ones that start recomposing too often. You see the result in Android Studio, in the CLI, or in logcat. Zero config required beyond applying the Gradle plugin.

• CI guardrail — fail builds when recomposition budgets regress
• IDE feedback — inspect hot spots, timeline spikes, and stability issues without leaving Android Studio
• Fast local checks — use the CLI to run check, snapshot, diff, and watch workflows

• Budget classes — auto-classifies composables (Screen, Container, Interactive, List Item, Animated, Leaf) with appropriate rate budgets
• Violation detection — alerts when a composable exceeds its budget, with throttled logging to avoid noise
• Call-tree hierarchy — tracks parent-child composition relationships
• Skip tracking — monitors skip rate to identify composables that recompose without actual changes
• Forced vs param-driven — distinguishes parent-forced recompositions from parameter-change-driven ones
• Dynamic budget scaling — multiplies budgets during scrolling (2x), animation (1.5x), and user input (1.5x)
• @ReboundBudget annotation — override the inferred budget class for any composable
• Baseline regression detection — snapshot metrics before/after and compare for regressions
• IDE tool window — 5-tab performance cockpit (Monitor, Hot Spots, Timeline, Stability, History) with editor integration (gutter icons, CodeVision inlays, status bar widget) and session persistence
• CLI — doctor, check, snapshot, summary, watch, ping commands over ADB socket

1. Apply the Gradle plugin

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

// build.gradle.kts (app module)
plugins {
    id("io.github.aldefy.rebound") version "0.2.2"
}

2. Configure (optional)

rebound {
    enabled.set(true)    // default: true
    debugOnly.set(true)  // default: true — only instruments debug builds
}

3. Run your app

Rebound auto-installs on first composition. Violations appear in logcat:

W/Rebound: [VIOLATION] MyScreen — 8 recomp/s (budget: 3, class: SCREEN)

4. Prove the runtime path

Run the CLI while the debug app is open:

./rebound-cli.sh doctor   # Diagnoses tools, device, socket, and ADB forwarding
./rebound-cli.sh check    # Proves ping + snapshot + summary data is flowing
./rebound-cli.sh summary  # Shareable top recomposition risks for PRs, agents, or CI

doctor tells you why setup is broken. check proves the app is reachable and emitting JSON metrics. summary is the compact output to paste into reviews or automation.

Connect the IDE plugin for richer live output.

The repo includes a sample app that intentionally violates a screen-level recomposition budget by reading a 60fps ticker at BudgetViolationScreen scope.

./gradlew :sample:installDebug
adb shell am start -n io.aldefy.rebound.sample/.MainActivity

./rebound-cli.sh doctor
./rebound-cli.sh check
./rebound-cli.sh summary

Expected signal: BudgetViolationScreen appears over its SCREEN budget. Tap Fixed in the sample app, wait a few seconds, then rerun summary to see the fast state isolated in an ANIMATED child.

The compiler plugin injects ReboundTracker.onCompositionEnter/Exit calls into every @Composable function at the IR level. The runtime tracks rates per sliding window and reports violations. The IDE plugin and CLI connect via LocalServerSocket("rebound") forwarded through ADB (Android) or via a WebSocket relay (iOS physical devices).

Platform support: The compiler plugin instruments all KMP targets. Android uses LocalServerSocket + ADB forward. iOS simulator uses a direct TCP server on :18462. iOS physical devices connect outbound to a Mac-side WebSocket relay via Bonjour auto-discovery, with console logging as fallback.

rebound {
    enabled.set(true)    // Master switch — set false to disable all instrumentation
    debugOnly.set(true)  // Only instrument debug builds (release builds get no overhead)
}

Runtime toggles:

ReboundTracker.enabled = true            // Master on/off at runtime
ReboundTracker.logCompositions = false   // Per-composition logcat (throttled 1/s per composable)

Each composable is auto-classified by IR heuristics:

• What: Full-screen composables — the root of navigation destinations.
• Heuristic: Name contains Screen or Page.
• Why 3/s: Screens should only recompose on navigation events or major state changes. If a screen recomposes more than 3 times per second, state is leaking upward.
• Example violation: Reading a frequently-changing state (e.g., scroll position, animation progress) at screen level instead of hoisting it down.
• Fix: Hoist the changing state to the child that needs it. Use derivedStateOf or move reads into a smaller scope.

• What: Layout composables with child @Composable calls — Column, Row, Box, Scaffold content slots.
• Heuristic: Has child @Composable calls in its body.
• Why 10/s: Containers recompose when children's layout changes. Moderate rate expected, but sustained high rates indicate unnecessary invalidation.
• Example: A Column that recomposes because a child's size changed or an unstable lambda is being passed.

• What: Composables responding to user input — buttons, text fields, sliders.
• Heuristic: Default for unclassified composables.
• Why 30/s: Users type and tap fast. Input-driven composables need headroom for responsive UX.

• What: Items inside LazyColumn, LazyRow, LazyGrid.
• Heuristic: Inside a lazy layout scope.
• Why 60/s: During fast scroll, items are recycled at up to 60fps. One recomposition per frame is expected.

• What: Composables driven by animation APIs.
• Heuristic: Calls animate*, Transition, Animation, or Animatable APIs.
• Why 120/s: Animations target 60-120fps. This budget gives room for the animation to run without false alarms.

• What: Terminal composables with no child @Composable calls — Text(), Icon(), Image().
• Heuristic: No child @Composable calls in the function body.
• Why 5/s: Individually cheap but shouldn't thrash. If a leaf recomposes >5/s, something upstream is pushing unnecessary state changes.

// This composable uses tilt sensor — it's not a leaf, it's animated
@ReboundBudget(BudgetClass.ANIMATED)
@Composable
fun TiltDrivenSticker(offset: Offset) { ... }

The Android Studio plugin (targets 2024.2.1.3+) provides a 5-tab performance cockpit, editor integration, and session persistence. Configure via Preferences > Tools > Rebound.

Monitor — Live composable tree with sparkline rate history per node. Scrolling event log at the bottom shows recomposition events, violations, and state changes in real time.

Hot Spots — Sortable flat table of all tracked composables, ranked by severity (OVER > NEAR > OK). Summary card at the top shows violation/warning/OK counts at a glance. Click any row to jump to source.

Timeline — Composable x time heatmap. Each cell is colored green/yellow/red based on budget status at that moment. Scroll back up to 60 minutes. Useful for correlating recomposition spikes with user interactions.

Stability — Parameter stability matrix showing SAME/DIFFERENT/STATIC/UNCERTAIN status per parameter for each composable. Cascade impact tree visualizes how unstable parameters propagate recompositions through the hierarchy.

History — Saved sessions stored in .rebound/sessions/. Each session is VCS-tagged with branch name and commit hash. Side-by-side comparison view for before/after regression analysis.

• Gutter icons — Red, yellow, or green dots next to @Composable function declarations, reflecting live budget status.
• CodeVision — Inline hints above each composable function: > 12/s | budget: 8/s | OVER | skip: 45%.
• Status bar — Persistent widget at the bottom of the IDE: Rebound: 45 composables | 3 violations.

The plugin connects via adb forward tcp:18462 localabstract:rebound. Install from the rebound-ide build output.

The CLI auto-detects the connection path: direct TCP (iOS simulator or relay), ADB forward (Android), or devicectl console (iOS physical without relay).

./rebound-cli.sh doctor     # Diagnose tools, device, socket, and ADB forwarding
./rebound-cli.sh check      # Ping + snapshot + summary sanity check
./rebound-cli.sh summary    # Top 10 composables by recomposition rate
./rebound-cli.sh snapshot   # Full JSON metrics for all tracked composables
./rebound-cli.sh watch      # Live updates every 1 second
./rebound-cli.sh ping       # Health check → "pong"

Or query directly:

echo "snapshot" | nc localhost 18462

For iOS physical devices, the runtime connects outbound to a Mac-side relay via WebSocket. The device discovers the relay automatically via Bonjour.

# Build the relay (one-time)
./tools/build-relay.sh

# Start the relay on your Mac
./tools/rebound-relay
# → TCP :18462 (CLI/IDE), WebSocket :18463 (devices), Bonjour: _rebound._tcp

# Now run your app on the physical device (same WiFi network)
# The device auto-discovers the relay and connects
./rebound-cli.sh snapshot   # works transparently through relay

Override Bonjour discovery with an env var if needed (e.g., different subnet):

REBOUND_RELAY_HOST=192.168.1.100:18463

The Gradle plugin auto-detects your project's Kotlin version and selects the correct compiler artifact. No manual configuration needed.

Why multiple artifacts? Kotlin's compiler plugin IR API changes between minor versions. Each artifact is compiled against the matching kotlin-compiler-embeddable to ensure binary compatibility.

See roadmap.md for the full iOS roadmap.

• [x] iOS transport — TCP server (simulator) + WebSocket relay (physical device) + console fallback
• [x] CI budget gates — fail builds when recomposition budgets regress
• [ ] Flame chart mode in Timeline tab
• [x] JetBrains Marketplace publication
• [ ] Session export/import for team sharing
• [x] Baseline snapshots for regression testing
• [ ] ComposeProof integration for LLM-driven analysis
• [ ] DNS resolution for relay host override
• [ ] Multi-device relay routing

Make your AI coding tool understand Compose recomposition performance. The rebound-skill repo contains markdown-based instructions that any AI assistant can consume.

What it covers: Budget classes, violation diagnosis, skip rate analysis, stability optimization, CLI usage, IDE plugin workflow — all backed by the actual Rebound codebase.

Supports: Claude Code, Gemini CLI, Gemini (Android Studio), Cursor, Copilot, Codex, Windsurf, Amazon Q, and any markdown-consuming AI tool.

See aldefy/rebound-skill for setup instructions.

Full documentation at aldefy.github.io/compose-rebound.

# Build all modules
./gradlew build

# Build IDE plugin
./gradlew :rebound-ide:buildPlugin
# Output: rebound-ide/build/distributions/rebound-ide-0.2.2.zip

# Run sample app
./gradlew :sample:installDebug

Copyright 2025 Adit Lal

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.