debroid

Name: debroid
Author: PatilShreyas

Pending

Autonomous, headless Android debugger designed for AI coding agents. Inspect runtime memory, set breakpoints, and debug live apps.

60stars

4forks

Kotlin

Installation

# Add to your Claude Code skills
git clone https://github.com/PatilShreyas/debroid

Getting Started

Guides for using ai agents skills like debroid.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

README.md

Frequently Asked Questions

What is debroid?

debroid is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by PatilShreyas. Autonomous, headless Android debugger designed for AI coding agents. Inspect runtime memory, set breakpoints, and debug live apps. It has 60 GitHub stars.

Is debroid safe to use?

debroid's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.

How do I install debroid?

Clone the repository with "git clone https://github.com/PatilShreyas/debroid" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is debroid written in?

debroid is primarily written in Kotlin. It is open-source under PatilShreyas on GitHub, so you can review or fork the full source.

Are there alternatives to debroid?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh debroid against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

238,080

redaktura-skills remote-gpu-trainer

Debroid (DEBug + AnDROID) is a headless CLI that speaks the Java Debug Wire protocol (JDWP) so AI agents — Claude Code, Grok Build, Codex, OpenCode, Cursor, Antigravity, or anything with a terminal — can debug a live Android app the way a human would in Android Studio: set breakpoints, catch exceptions, step through code, inspect and mutate variables, and watch fields — all without a GUI, and all through strict, machine-parseable JSON.

❓ Why it exists

Traditional Android development environments are highly visual. While AI coding assistants can write code, they are effectively "blind" when it comes to runtime debugging because they cannot click through the Android Studio UI to inspect memory or pause execution.

Debroid closes this gap. It acts as a translation layer between the raw terminal (which AI agents are great at using) and the Android Virtual Machine. By providing a CLI that outputs deterministic JSON, an AI agent can autonomously hypothesize a bug, launch the app, trap the exact line of code, read the live state of the device, and evaluate a fix — granting agents the same deep runtime awareness previously reserved for human developers.

✨ Features

🔴 Breakpoints: Set line breakpoints in any class. Debroid automatically defers them if the class isn't loaded yet.
⚡ Exception Traps: Catch caught or uncaught exceptions globally across the app.
👀 Watchpoints: Monitor field access and modification live.
🔬 Deep Inspection: Recursively inspect deep object memory, local variables, and call frames with built-in cycle-guards.
🧬 Live Mutation: Modify variable memory dynamically on paused threads using set-var.
🧮 Live Evaluation: Fully-featured expression evaluator supporting Java syntax, method calls, and arithmetic directly in the target VM.
🐾 Stepping: Step Over, Step Into, Step Out, or Resume at will.
🧵 Coroutine Aware: Built-in mechanism to extract shallow locals from Kotlin Continuation frames.

🚀 Installation

[!TIP] Let your AI Agent do it for you! Copy & paste this prompt directly to your AI agent:
Read https://raw.githubusercontent.com/PatilShreyas/debroid/main/README.md and install the Debroid CLI and its skill globally for me.

Prerequisites

Java JDK 11+ (JAVA_HOME)
Android SDK & adb configured in your PATH

Install the CLI

Option 1: Quick Install (Pre-built Release Binary) Run the one-liner script to download the latest release binary and install it:

curl -fsSL https://raw.githubusercontent.com/PatilShreyas/debroid/main/install.sh | bash

Option 2: Local Build Install (Build from Source) Clone the repository and build locally:

./install.sh

To completely remove Debroid from your system:

Stop any active background daemon sessions:
```
debroid stop
```
Remove the binary executable from your user local directory:
```
rm ~/.local/bin/debroid
```

🧠 AI Agent Skill Setup

Debroid is designed to be operated autonomously by AI agents. To teach your agent how to use Debroid effectively, provide it with the skill instructions (SKILL.md).

The skill file is embedded directly inside the debroid CLI binary (debroid skill) and hosted on GitHub.

Select your AI agent below for setup instructions and exact skill paths:

mkdir -p ~/.gemini/skills/debroid && debroid skill > ~/.gemini/skills/debroid/SKILL.md

mkdir -p ~/.claude/skills/debroid && debroid skill > ~/.claude/skills/debroid/SKILL.md

mkdir -p .cursor/rules && debroid skill > .cursor/rules/debroid.mdc

mkdir -p ~/.grok/skills/debroid && debroid skill > ~/.grok/skills/debroid/SKILL.md

mkdir -p ~/.codex && debroid skill >> ~/.codex/AGENTS.md

mkdir -p ~/.config/opencode/skills/debroid && debroid skill > ~/.config/opencode/skills/debroid/SKILL.md

(Note: If you haven't installed the CLI binary yet, replace debroid skill with curl -fsSL https://raw.githubusercontent.com/PatilShreyas/debroid/main/skills/debroid-cli/SKILL.md in any command).

🔌 How it Works

Debroid separates the persistent debugging connection from the transient CLI commands to maintain state across agent invocations.

flowchart LR
    A["🤖 AI Agent\n(Terminal / CLI)"] <-->|Terminal Commands| B("⚡ Debroid Daemon\n(Background Server)")
    B <-->|JDWP over ADB| C["📱 Android App\n(Dalvik/ART VM)"]

The AI Agent runs debroid commands in the terminal (e.g. debroid break ...).
The Debroid CLI forwards these requests to the Debroid Daemon, which starts automatically in the background on the first command.
The Debroid Daemon holds the long-lived JDWP socket connection open via ADB port forwarding, managing the breakpoints, event queue, and thread states of the Android App.
The Daemon returns the result back to the CLI as a strict JSON payload, which the Agent reads from standard output.

📖 Command Reference

Here is the full list of commands and their signatures (note: all JSON commands accept an optional --pretty flag to format response JSON, and an eager --schema flag to inspect output types):

Command	Signature	Description
`daemon`	`debroid daemon`	Starts the persistent background daemon
`stop`	`debroid stop [--pretty]`	Shuts down background daemon and detaches all active sessions
`launch`	`debroid launch <app_id> [--pretty]`	Launches app suspended and attaches (auto-clears set-debug-app on detach)
`attach`	`debroid attach <app_id> [--pretty]`	Attaches to a running app
`detach`	`debroid detach <session_id> [--pretty]`	Safely detaches debugger; for `launch` sessions also clears `am set-debug-app`
`break`	`debroid break <session_id> <file> <line> [-p/--package=<pkg>] [--pretty]`	Sets a line breakpoint (auto-defers if class isn't loaded yet)
`remove-break`	`debroid remove-break <session_id> <breakpoint_id> [--pretty]`	Removes a line breakpoint
`catch-exception`	`debroid catch-exception <session_id> [class_name] [--caught] [--uncaught] [--pretty]`	Sets an exception breakpoint (default: `--uncaught` only)
`remove-catch-exception`	`debroid remove-catch-exception <session_id> <exception_breakpoint_id> [--pretty]`	Removes an exception breakpoint
`watch`	`debroid watch <session_id> <class_name> <field_name> [--access] [--modify] [--pretty]`	Sets a field watchpoint (default: access+modify)
`remove-watch`	`debroid remove-watch <session_id> <watchpoint_id> [--pretty]`	Removes a watchpoint
`threads`	`debroid threads <session_id> [--pretty]`	Lists active threads
`locals`	`debroid locals <session_id> <thread_id> [--pretty]`	Gets shallow local variables
`pause-state`	`debroid pause-state <session_id> <thread_id> [--pretty]`	Gets frames, locals, and instance state
`set-var`	`debroid set-var <session_id> <thread_id> <var_name> <new_value> [--pretty]`	Mutates local variable
`eval`	`debroid eval <session_id> <thread_id> <expression...> [--pretty]`	Evaluates string expression
`resume`	`debroid resume <session_id> [--pretty]`	Resumes all threads
`poll`	`debroid poll <session_id> [cursor=0] [--with-stacktrace] [--pretty]`	Polls for asynchronous debugger events
`frames`	`debroid frames <session_id> <thread_id> [--pretty]`	Retrieves thread stack frames
`coroutine`	`debroid coroutine <session_id> <continuation_id> [--pretty]`	Retrieves locals from a Continuation object
`inspect`	`debroid inspect <session_id> <object_id> [-d/--max-depth=<int>] [--pretty]`	Inspects deep object fields (`nested` map populated when `--max-depth > 1`)
`step`	`debroid step <session_id> <thread_id> <action> [--pretty]`	Steps execution (`STEP_OVER`, `STEP_INTO`, `STEP_OUT`, `RESUME_THREAD`, `RESUME_ALL`)
`update`	`debroid update [--check-only] [--pretty]`	Checks for CLI updates or performs an in-place self-update to the latest release
`skill`	`debroid skill`	Prints the embedded AI Agent skill instructions (`SKILL.md`) to stdout

Security Note: The Debroid daemon listens on localhost (127.0.0.1) without authentication to enable fast communication with the CLI. It exposes live JVM manipulation. Only run Debroid on a machine where every local user is fully trusted.

🤝 Contributing

We welcome contributions! If you're building an AI agent or improving the underlying JDI wrappers, please see AGENTS.md for architectural guidelines and rules for maintaining the strict JSON CLI contract.

If Debroid saves your agent from a debugging dead end, consider giving the repo a ⭐ - it helps others find it :)

📄 License

This project is licensed under the [Apache 2.0 License