DroidDoctor 🤖🩺

AI-powered Android project health analyzer built with LangGraph

Point it at any Android project. Get a full health report in 30 seconds.

pip install droiddoctor
droiddoctor ~/AndroidStudioProjects/MyApp

Why This Exists

Android projects rot silently. AGP falls behind, Compose BOM drifts, exported components leak, deprecated APIs linger, permissions creep.

You know you should audit. But it's scattered across lint, dependency checks, manual manifest review, and that one senior dev who "just knows."

DroidDoctor does the full audit in one command.

What It Checks

Check	What It Does
Gradle Dependencies	Parses `build.gradle(.kts)` + `libs.versions.toml`, checks every dep against Google Maven and Maven Central for latest versions
Manifest Security	Exported components without permissions, dangerous permissions, cleartext traffic, hardcoded debuggable flag, missing backup rules
Deprecated APIs	Regex scan for `AsyncTask`, `startActivityForResult`, `ViewModelProviders.of`, `android.support.*`, `kapt`, `findViewById`, and 7 more patterns
Compose Adoption	Measures XML layout vs `@Composable` file split across all modules with adoption percentage
AI Analysis	LLM synthesizes all findings into a prioritized action plan: 🚨 FIX NOW / ⚠️ THIS SPRINT / 📋 NEXT QUARTER

Architecture

A 7-node LangGraph agent with conditional routing and shared state:

                    ┌──────────────────────────┐
         ┌────────►│ analyze_gradle_dependencies│────────┐
         │         └──────────────────────────┘          │
         │                                               │
┌────────┴──────┐  ┌──────────────────────────┐          ▼
│ scan_project  │─►│     audit_manifest        │──► ┌──────────┐    ┌─────────────┐    ┌─────────────┐
│  _structure   │  └──────────────────────────┘     │ collect  │───►│ llm_analyze │───►│  generate   │
└────────┬──────┘  ┌──────────────────────────┐     │ _results │    │             │    │  _report    │
         │         │  detect_deprecated_apis   │──► └──────────┘    └─────────────┘    └─────────────┘
         │         └──────────────────────────┘          ▲
         │         ┌──────────────────────────┐          │
         └────────►│  check_compose_adoption   │─────────┘
                   └──────────────────────────┘

Design philosophy: The LLM never scans files. Static analysis handles scanning — it's deterministic and fast. The LLM only does what LLMs are good at: correlating findings, prioritizing by risk, and generating actionable explanations.

Quick Start

1. Install

pip install droiddoctor

Or from source:

git clone https://github.com/samuvelp/droiddoctor.git
cd droiddoctor
pip install -e .

2. Set your API key

export ANTHROPIC_API_KEY=sk-ant-xxxxx

Or create a .env file:

ANTHROPIC_API_KEY=sk-ant-xxxxx

3. Run

droiddoctor /path/to/your/android/project

Multi-Provider Support

DroidDoctor supports 5 LLM providers. Use whatever key you already have:

# Claude (default)
export ANTHROPIC_API_KEY=sk-ant-...
droiddoctor /path/to/project

# OpenAI
pip install langchain-openai
export OPENAI_API_KEY=sk-...
droiddoctor /path/to/project --provider openai

# Google Gemini
pip install langchain-google-genai
export GOOGLE_API_KEY=...
droiddoctor /path/to/project --provider gemini

# Groq (free tier available)
pip install langchain-groq
export GROQ_API_KEY=gsk_...
droiddoctor /path/to/project --provider groq

# Ollama (fully local — no API key needed)
pip install langchain-ollama
droiddoctor /path/to/project --provider ollama --model llama3.1

Override the default model for any provider:

droiddoctor /path/to/project --provider openai --model gpt-4.1
droiddoctor /path/to/project --provider gemini --model gemini-2.5-flash

Usage

# Full scan with AI analysis
droiddoctor /path/to/android/project

# Save markdown report to file
droiddoctor /path/to/project --save

# Custom output path
droiddoctor /path/to/project --save -o health-report.md

# Offline mode — skip LLM, just raw data (no API key needed)
droiddoctor /path/to/project --no-llm

# Use a specific LLM provider
droiddoctor /path/to/project --provider openai

# Show version
droiddoctor --version

Example Output

╭────────────────────────────────────────────╮
│  DroidDoctor v0.1.0                        │
│  AI-powered Android project health analyzer│
╰────────────────────────────────────────────╯

╭────────────── Health Score — MyApp ──────────────╮
│                    62/100 🟠                      │
│               3 module(s) scanned                │
╰──────────────────────────────────────────────────╯

                  Outdated Dependencies
┌──────────────────────────┬─────────┬────────┬──────────┐
│ Dependency               │ Current │ Latest │ Severity │
├──────────────────────────┼─────────┼────────┼──────────┤
│ com.android.tools.build  │ 8.2.0   │ 8.7.0  │ CRITICAL │
│ org.jetbrains.kotlin     │ 1.9.22  │ 2.1.0  │ MAJOR    │
│ androidx.core:core-ktx   │ 1.10.0  │ 1.15.0 │ MINOR    │
└──────────────────────────┴─────────┴────────┴──────────┘

                    Manifest Issues
┌──────────┬──────────────────────────────────────────┐
│ Severity │ Issue                                    │
├──────────┼──────────────────────────────────────────┤
│ CRITICAL │ Cleartext (HTTP) traffic enabled         │
│ CRITICAL │ android:debuggable="true" hardcoded      │
│ WARNING  │ Dangerous permission: CAMERA             │
│ WARNING  │ Exported activity without permission     │
└──────────┴──────────────────────────────────────────┘

                   Deprecated APIs
┌────────────────────────┬────────────────────────────┐
│ API                    │ Replacement                │
├────────────────────────┼────────────────────────────┤
│ AsyncTask              │ Kotlin Coroutines          │
│ startActivityForResult │ Activity Result API        │
│ ViewModelProviders.of  │ by viewModels() delegate   │
│ kapt                   │ Migrate to KSP             │
└────────────────────────┴────────────────────────────┘

╭─── Compose Adoption ────────────────────────────────╮
│ XML Layouts: 42  |  Composable Files: 12  |  22.2% │
│ ████░░░░░░░░░░░░░░░░ 22.2%                         │
╰─────────────────────────────────────────────────────╯

╭─── AI-Powered Analysis ─────────────────────────────╮
│                                                      │
│  🚨 FIX NOW                                         │
│  • Remove android:debuggable="true" — this makes    │
│    your release APK debuggable in production         │
│  • Disable cleartext traffic — user data is being   │
│    sent over unencrypted HTTP                        │
│                                                      │
│  ⚠️ FIX THIS SPRINT                                 │
│  • Update AGP 8.2.0 → 8.7.0 — you're missing       │
│    build performance improvements and R8 fixes       │
│  • Replace AsyncTask with viewModelScope.launch —   │
│    deprecated since API 30                           │
│                                                      │
│  📋 PLAN FOR NEXT QUARTER                            │
│  • Compose is at 22% — create a migration tracker   │
│    and convert one screen per sprint                 │
│                                                      │
╰─────────────────────────────────────────────────────╯

What It Handles

Single or multi-module — reads settings.gradle(.kts) to discover all modules
Groovy or Kotlin DSL — parses both build.gradle and build.gradle.kts
Version catalogs — full gradle/libs.versions.toml support with version ref resolution
Network failures — if Maven version checks fail, skips gracefully and continues
No Compose projects — works fine on 100% XML projects, reports without judgment
Large projects — automatically skips .gradle/, build/, .idea/, node_modules/

Project Structure

droiddoctor/
├── droiddoctor/
│   ├── cli.py               # CLI entry point — rich terminal UI
│   ├── graph.py              # LangGraph definition — 7 nodes, conditional routing
│   ├── state.py              # AgentState TypedDict + data models
│   ├── nodes/
│   │   ├── scanner.py        # Node 1: Discover project layout and modules
│   │   ├── gradle.py         # Node 2: Parse deps, check versions via HTTP
│   │   ├── manifest.py       # Node 3: Security audit of AndroidManifest.xml
│   │   ├── deprecated.py     # Node 4: Regex scan for 13 deprecated patterns
│   │   ├── compose.py        # Node 5: XML vs Composable adoption metrics
│   │   ├── analyzer.py       # Node 6: LLM synthesis + health score
│   │   └── reporter.py       # Node 7: Final markdown report generation
│   └── parsers/
│       ├── gradle_parser.py   # build.gradle(.kts) + libs.versions.toml parser
│       └── manifest_parser.py # AndroidManifest.xml parser (xml.etree)
├── tests/
│   ├── fixtures/              # Sample Android project files for testing
│   └── test_nodes.py          # 22 tests covering all parsers and nodes
├── pyproject.toml
├── requirements.txt
├── .env.example
└── LICENSE

How to Extend

Each node is a pure function: (AgentState) -> dict. To add a new check:

Create a new node in droiddoctor/nodes/
Read what you need from AgentState, return only the keys you update
Wire it into the graph in graph.py with add_node() + add_edge()
Add a table for it in reporter.py

Ideas for new nodes:

ProGuard/R8 rules audit — missing keep rules
Room migration checker — detect missing migration paths
API level compatibility — flag APIs unavailable on minSdk
Test coverage estimator — test files vs source files ratio
CI config checker — missing lint/test steps in GitHub Actions

Contributing

Contributions welcome! Good first issues:

Groovy build.gradle test fixtures
buildSrc and convention plugin support
JSON output format (--format json)
True parallel fan-out for analysis nodes
GitHub Actions integration
HTML report output
Diff mode — compare two scans

License

MIT — see LICENSE

samuvelp/droiddoctor

README