patilshreyas/debroid/debroid-cli

Debroid CLI Debugger Skill

This skill provides mandatory instructions for AI agents to use the debroid CLI for headless Android debugging. Follow these instructions strictly to avoid context window bloat and execution errors.

🎯 Trigger Conditions

Activate this skill whenever the user or task involves:

• Debugging an Android application or process live
• Setting line breakpoints in Kotlin or Java source files (debroid break)
• Catching uncaught or caught runtime exceptions (debroid catch-exception)
• Inspecting live variables, object memory, or Jetpack Compose state (debroid locals, pause-state, inspect)
• Stepping through Kotlin/Java code execution (debroid step)
• Monitoring field access or modifications with watchpoints (debroid watch)
• Evaluating expressions or mutating variable values in runtime memory (debroid eval, set-var)

⚠️ Critical Agent Rules (DO NOT IGNORE)

1. Always use `--with-stacktrace` when polling to get immediate context.
2. Never poll in an infinite loop. Poll once or twice, and if the app hasn't hit a breakpoint, instruct the user to interact with the app.
3. Parse JSON outputs carefully. All CLI outputs are JSON strings. Extract sessionId, threadId, objectId, breakpointId, exceptionBreakpointId, watchpointId, and continuationId exactly as provided and reuse them verbatim in subsequent commands. Do not synthesize IDs.
4. Track trap IDs and remove them when done. Every break, catch-exception, and watch returns an ID. Use remove-break, remove-catch-exception, remove-watch to clear traps you no longer need so they don't fire unexpectedly and waste poll cycles.
5. Keep IDs in working memory, not in long scratch buffers. A typical session uses 1–3 trap IDs plus 1 thread ID — keep them inline.
6. Use Background Tasks: If you are using an agentic system that supports background tasks, run debroid daemon as a background task.
7. Token efficiency & Schema Inspection: All JSON responses are compact single-line by default to conserve agent context tokens. If formatted multi-line JSON is required, append the --pretty flag to any JSON command. To inspect the expected output JSON structure for any command without running a session, pass the --schema flag (e.g., debroid pause-state --schema). Do not echo full responses back to the user verbatim — summarize the relevant fields (valuePreview, type, objectId, location).
8. Self-Recovery: If a session becomes unresponsive or gets out of sync, run debroid stop to cleanly terminate the daemon and release ADB ports. The next debroid command will auto-restart a fresh daemon.
9. Report, but don't block: If you hit unexpected Debroid behavior or have feedback on the tool itself, first try to resume the flow of what the user originally wanted to perform. Do not immediately jump to reporting the issue. At the end of your task, ask the user if they want to report the issue. See "🐛 Reporting Bugs & Feedback" below for details.

🔄 Standard Debugging Workflow

Step 1: Start the Daemon

Debroid requires a persistent background daemon to communicate with the Android device via JDWP.

debroid daemon &

(Wait 1-2 seconds for it to start). The first CLI command will also auto-start the daemon if it isn't running.

Step 2: Attach to the App

You must attach the debugger to obtain a sessionId.

• If the user wants to debug app startup:

``bash debroid launch <app_id> debroid break <session_id> <FileName.kt> <line_number> --package <pkg> debroid resume <session_id> ` > ⚠️ launch starts the app suspended via am set-debug-app -w and halts the VM with all threads suspended (suspendedThreadsCount > 0). Set your startup breakpoints or watchpoints immediately after launch, and then call debroid resume <session_id> so the VM proceeds with startup and hits your breakpoints. (Pass --no-suspend if you want the app to start executing immediately upon launch without waiting). > ⚠️ launch uses am set-debug-app -w. Debroid **automatically** clears this flag when you call detach, so the next normal (non-debug) launch of the app will not hang. Do not call am clear-debug-app` yourself.

• If the app is already running:

``bash debroid attach <app_id> ` *(Pass --suspend if you want to suspend all threads immediately upon attaching).* **Action:** Extract the sessionId` from the JSON response.

⚠️ Session Lifecycle & Breakpoints (Crucial!):

Breakpoints, watchpoints, and exception traps are strictly session-scoped. When you call attach or launch for an app_id that is already being debugged by an older/stale session, Debroid's automatic deduping will instantly safely detach that stale session. This completely wipes all breakpoints and watchpoints you may have set previously. You MUST recreate any breakpoints or watchpoints you need using your new sessionId returned by the new attach/launch command!

Step 3: Set Traps

Set your breakpoints or watchpoints before polling. Save the returned IDs.

• Line Breakpoint: debroid break <session_id> <FileName.kt> <line_number> [--package <pkg>] [--pretty] → returns { "id": "bp_1", "verified": true|false, ... }
• Always pass `--package` when you know it (e.g. --package com.example.app.search). Providing the package name lets the daemon resolve the class with a single targeted lookup instead of scanning every loaded class across the entire VM, which takes seconds or minutes on large applications and drastically improves responsiveness.
• If verified=false, the class isn't loaded yet. Debroid will automatically bind it the moment the class is prepared — you do not need to do anything; just poll. (No more deferred-breakpoint dead-ends.)
• Use remove-break <session_id> <breakpoint_id> to clear it.
• Exception Trap: debroid catch-exception <session_id> [ExceptionClass] [--caught] [--uncaught]
• Defaults: --uncaught ON, --caught OFF. Add --caught to also trap exceptions caught by the app.
• Returns { "exceptionBreakpointId": "ex_bp_1" }.
• Remove with remove-catch-exception <session_id> <exception_breakpoint_id>.
• Watchpoint: debroid watch <session_id> <com.pkg.Class> <fieldName> [--access] [--modify]
• Defaults: BOTH access and modify ON. Pass --no-access or --no-modify to disable either.
• Returns { "watchpointId": "wp_1" } (or an INVALID_ARGUMENT error if the target class is already loaded and <fieldName> does not exist on it).
• Remove with remove-watch <session_id> <watchpoint_id>.

Step 4: Poll for Events

You must poll the event queue to see if a trap was triggered.

debroid poll <session_id> <cursor> --with-stacktrace

• Initial Cursor: Always start with "0".
• Subsequent Cursors: Use the nextCursor value from the previous JSON response.
• Buffer Overflow & Stale Cursors: Inspect droppedEventsSinceLastPoll (omitted from JSON when 0). If present and > 0, events were evicted from the buffer before they could be polled (e.g. due to high event volume or delayed polling). If an expected breakpoint or exception event is not present in events, it may have been among the dropped events.
• Waiting: If events is empty, ask the user to trigger the action in the app, then poll again.
• Event types you may see: BREAKPOINT_HIT (includes breakpointId), STEP_HIT, EXCEPTION_HIT (exceptionMessage includes <ExceptionClass>: <detailMessage>), WATCHPOINT_ACCESS_HIT (includes stacktrace when --with-stacktrace is set), WATCHPOINT_MODIFY_HIT (includes stacktrace when --with-stacktrace is set), DISCONNECT.

Step 5: Inspect the Pause State

Once poll returns an event (e.g., BREAKPOINT_HIT), extract the threadId. Use the Pause State Command to get frames and locals at once:

debroid pause-state <session_id> <thread_id>

Advanced Inspections:

• Drill into complex objects or arrays: debroid inspect <session_id> <object_id> [OPTIONS]
• --max-depth N recurses N levels deep into object fields and array elements. Responses include a nested map keyed by field name (or array index "[0]", "[1]", ...). Cycles are guarded automatically.
• Array Inspection: Inspecting an array objectId (or a collection's backing array) populates fields (and nested when --max-depth > 1) with indexed keys ("[0]", "[1]", ...).
• Important Filter Behavior: By default, inspect explicitly filters out static fields, synthetic fields, and ART-specific internal fields (shadow$_*). It also prevents redundant recursion into well-known immutable terminal types (like java.lang.String and Enums) to save your context tokens.
• --include-static and --include-internal can be passed to bypass these filters if you absolutely need to inspect Dalvik internals or static class constants.
• Coroutine state: debroid coroutine <session_id> <continuation_id>

ObjectId Lifecycle & Reuse (Crucial!):

Any objectId or continuation_id returned by ANY command (including locals, pause-state, poll stacktraces, eval, or even inside a deeply nested inspect result) is globally cached by the daemon and guaranteed to remain valid and reusable across multiple standalone commands for the entire duration of the current suspend. You can confidently extract nested objectIds from a shallow inspect and drill into them later. These IDs are only invalidated/cleared when the VM is explicitly resumed (e.g. via step, resume) or detached.