Debroid CLI Debugger

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.