Debroid CLI
A headless Android debugger on JDWP: the agent sets breakpoints and reads variables, and every answer comes back as JSON
- 276 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Attaches to a running app over ADB and can change variable values and evaluate expressions in its virtual machine
- A background process keeps the device connection open until you call debroid stop
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/PatilShreyas/debroid/main/install.sh | bashDownloads a prebuilt binary into `~/.local/bin`. You can build from source by running `./install.sh` in a clone.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Attaches to a running app over ADB and can change variable values and evaluate expressions in its virtual machine
- A background process keeps the device connection open until you call debroid stop
This is third-party code. Review the repository files before installing.
What it does
Debroid is a command-line program that attaches to a running Android app over the Java Debug Wire Protocol and ADB. With no GUI, an agent sets line breakpoints, catches exceptions, watches fields, steps through code and reads locals and the call stack, the way a person does in Android Studio. Every command prints strict JSON. A background process holds the connection: it starts itself on the first command and keeps breakpoints and thread state between calls. If a class is not loaded yet, the breakpoint is deferred and fires later. The `set-var` command changes a variable on a paused thread, `eval` evaluates Java-syntax expressions inside the target virtual machine, and Kotlin coroutine frames can be unpacked for their locals. On first run the program extracts the agent instructions to `~/.debroid/skills/debroid-cli/SKILL.md`. Symlink that file into the target agent's skills folder and a CLI update refreshes the instructions too.
Who it is for. For Android developers on Kotlin and Java who let Claude Code, Codex or Cursor chase bugs on a running app.
Good fit when
- The agent suspects a bug but logs do not show variable values at the moment of failure
- You need to catch an unhandled exception across the whole app and read its call stack
- You must find out who changes an object field and when: watchpoints cover this
- You want to test a hypothesis by setting another variable value on a paused thread
- A bug reproduces inside a Kotlin coroutine and you need its locals
Not a fit when
- You need iOS or native code debugging: Debroid speaks JDWP to the ART virtual machine and debugs Java and Kotlin
- The machine has no JDK 11 or newer and no adb: both are required
- You want a visual overview of app state: the program answers in JSON only
- You cannot run the app under a debugger on a device where changing variable state is unwelcome
Example request
Launch the app with Debroid, set a breakpoint at line 42 in CartViewModel and show the local variables when it hitsLimitations
A Java JDK 11 or newer with `JAVA_HOME` and an Android SDK with adb on PATH are required. A background process holds the connection and `debroid stop` shuts it down. In `launch` mode the app starts suspended, and on detach the program clears the device's debug-app marker itself. Debugging goes over the Java Debug Wire Protocol, so only virtual-machine classes are visible. The output is built for programs to parse, and the `--pretty` flag formats it for people.
How to disable. Stop the background process with `debroid stop`, delete the binary at `~/.local/bin/debroid` and remove the symlinks to SKILL.md from the agents' skills folders.
FAQ
How do I install Debroid in Claude Code?
Run `curl -fsSL https://raw.githubusercontent.com/PatilShreyas/debroid/main/install.sh | bash`. Then symlink `~/.debroid/skills/debroid-cli/SKILL.md` into `~/.claude/skills/debroid/`; ready commands for Claude Code, Codex, Cursor, OpenCode, Grok Build and Antigravity are in the README.
What does Debroid need on the machine?
A Java JDK 11 or newer, the Android SDK and adb configured on PATH. The app must run on an emulator or a device visible over ADB.
How does an agent read Debroid output?
Every command prints JSON. The `--pretty` flag formats it for people and `--schema` shows the output types so the agent does not guess at fields.
What is the difference between launch and attach?
`debroid launch` starts the app suspended and attaches at once, then clears the `am set-debug-app` marker on detach. `debroid attach` connects to an app that is already running.
What are deferred breakpoints?
If the virtual machine has not loaded the class yet, Debroid remembers the point and sets it when the class appears. `debroid points` lists active and deferred points.
Discussion
No questions or reviews yet.
Related
CLI toolsSkill and CLI for controlling an Android phone via ADB and vision models: the agent opens apps, searches, orders and verifies results
Skills and a CLI that let Claude Code, Codex and OpenCode operate an Android phone: open apps, tap, type and test workflows
Awesome Android Agent Skills
awesome-android-agent-skills
Skills for modern Android development for Copilot, Claude, Gemini and Cursor: Kotlin, Jetpack Compose, architecture, Hilt, Room
Official set of 30 skills from the Android team: Jetpack Compose, AGP 9 upgrade, R8, Perfetto profiling, Navigation 3, CameraX, Google Play policies
An Android emulator in Docker with an MCP server: the agent drives the device over adb, opens apps and pages, presses buttons
The Flutter team's agent plugin: Flutter and Dart skills, the Dart MCP server and a hot reload rule for Claude Code, Cursor and Codex
README in short
The README explains why an agent needs a headless debugger: without one it sees only code and logs. It then gives installation, commands to link SKILL.md for six agents, a diagram of the background process between the CLI and the app, and a table of every command with its flags.