Android Insight

Pre-release notice: the selected product name and robot-derived icon remain under trademark and asset review. Public GitHub Release and Marketplace publishing are intentionally disabled by default. Review docs/legal-risk-assessment.md before public distribution.

Simplified Chinese documentation is included as README.zh-CN.md.

Android Insight is a local Gradle, device, and source-navigation workbench for Android™ projects in Visual Studio Code. It reads the evaluated Android Gradle Plugin model, uses the project's own Gradle Wrapper, and fails closed instead of inventing modules, variants, tasks, devices, or source links.

It is not a replacement for Android Studio, a Java/Kotlin language server, or a complete Android IDE. Completion, diagnostics, refactoring, debugging, receiver-type inference, and inherited-member navigation remain responsibilities of the installed language tooling.

Highlights

• Run configuration: select a real application module, enabled AGP variant, and verified ADB device; then assemble an APK, build an App Bundle, lint, clean, or run the complete build/install/launch transaction with live Gradle output.
• Gradle tasks: search and execute the complete task catalog currently reported by Gradle for Java across the open Gradle roots.
• Safe deployment: select installable APK outputs, let Android Package Manager authoritatively detect signature incompatibility, and never silently uninstall a conflicting application.
• Device workspace: manage connected devices, installed applications, package-scoped Logcat, and Android Virtual Devices from one panel.
• Android Projects: browse a lazy, source-focused projection of Android modules; create files/folders, rename files/folders, or move them to the system trash.
• Android Focus: hide reproducible .gradle, .idea, .kotlin, build, .cxx, .externalNativeBuild, and captures directories without deleting them.
• Exact source fallback: index only dependency sources.jar files and SDK sources proven for the selected module and variant, then resolve a bounded subset of Android/AndroidX definitions.
• Language Model Tools: expose explicit workspace, device, application, Gradle, deployment, and package-scoped Logcat tools to compatible VS Code Chat hosts. The extension does not contain its own model.

Quick start

1. Install the extension and its required Gradle and Java extensions.
2. Open a trusted Android Gradle workspace that contains gradlew or gradlew.bat.
3. Open the Android Insight Activity Bar view and refresh the evaluated project model.
4. Choose an application module, variant, and online device.
5. Run an action or open Gradle Tasks / Devices for the detailed workflows.

Android Studio is not required, but the project still needs its compatible Android SDK, JDK, Gradle Wrapper, and Android Gradle Plugin configuration.

Requirements

• Visual Studio Code 1.96 or newer
• Gradle for Java
• Language Support for Java by Red Hat
• Kotlin by JetBrains, recommended for Kotlin completion and diagnostics
• An Android project with a Gradle Wrapper
• Android SDK command-line tools and platform-tools
• A Java runtime compatible with the opened project's Gradle and AGP versions

The Android SDK is resolved from androidGo.sdkPath, the project's local.properties, ANDROID_SDK_ROOT, or ANDROID_HOME, in that order. No operating-system installation path or JDK version is guessed.

Untrusted workspaces and Virtual Workspaces are not supported because the extension executes the project Wrapper and local Android SDK tools.

Source navigation

When the evaluated model is ready, Android Insight resolves sources for the selected module and variant. Standard F12 and Android Insight: Go to Android Source prefer an exact indexed Android/AndroidX source and otherwise delegate to VS Code's native definition command.

The fallback supports source-proven types, nested types, selected top-level declarations, and selected extension members referenced by explicit imports or complete qualified names. It deliberately returns no result when ownership cannot be proven. It does not replace language-server completion or semantic analysis.

If SDK sources are missing, Android Insight: Sync Code Intelligence and SDK Sources opens sdkmanager in a visible terminal. The user remains responsible for reviewing and accepting the SDK terms and running synchronization again after installation.

See docs/source-navigation.md for the exact boundaries.

Safety and privacy

• Destructive application, AVD, and device-log actions require confirmation.
• A signature mismatch never causes a silent uninstall.
• AI deployment is non-interactive and reports signature conflicts instead of replacing the installed application.
• The extension has no first-party telemetry or network-upload implementation.
• When a user or agent invokes a Language Model Tool, its result is returned to the selected VS Code Chat/model provider and can contain workspace, device, application, or package-scoped Logcat data.

Read PRIVACY.md before enabling model tools on devices or projects containing confidential data.

Compatibility and known limits

The implementation targets the public Android Components APIs used by AGP 7.4–9 and Gradle 7.5 or newer, but this is a design range rather than an equal guarantee for every combination. Current concrete validation includes an AGP 8.12 multi-module application and an AGP 9.0 Kotlin Multiplatform Android library fixture. Unsupported or incomplete models remain fail-closed.

See docs/compatibility.md and docs/product-requirements.md for exact acceptance criteria and non-goals.

Documentation

• docs/product-requirements.md — product requirements
• docs/compatibility.md — compatibility matrix
• docs/source-navigation.md — source-navigation design and troubleshooting
• docs/ai-tools-and-privacy.md — AI tools and privacy boundaries
• docs/publishing.md — GitHub and Marketplace publishing
• docs/release-checklist.md — release gates
• docs/legal-risk-assessment.md — legal risk assessment
• SECURITY.md, SUPPORT.md, PRIVACY.md, NOTICE.md, and CHANGELOG.md

Local development

npm ci
npm run check
npm run test:monkey
npm run package
code --install-extension ./android-insight-*.vsix --force

npm run test:monkey starts a real local Extension Host with an isolated synthetic Android/Gradle/ADB fixture and reproducible non-destructive command sequences. Then run Developer: Reload Window, open a trusted Android project, and verify the model, module types, variants, build actions, device refresh, and source navigation with the packaged VSIX.

License and trademarks

Source code is licensed under the MIT terms in LICENSE. Third-party marks and assets remain the property of their respective owners. Android is a trademark of Google LLC. This project is independent and is not affiliated with, endorsed by, or sponsored by Google, Microsoft, Gradle, or JetBrains.

The current robot-derived icon is subject to this required attribution:

The Android robot is reproduced or modified from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.

NOTICE.md records the same attribution. Public publication remains gated on the name and icon decision in docs/legal-risk-assessment.md.