LldbAndroid

LldbAndroid is an agent skill for debugging and tracing Android native code with LLDB. It is designed for APKs, JNI libraries, Android .so files, Unity Android native libraries, and cross-platform Android remote debugging.

The primary entrypoint is a Python 3 CLI:

python scripts/android_lldb.py <subcommand> [options]

What This Skill Provides

• Cross-platform orchestration for Windows, Linux, and macOS hosts.
• Android remote debugging through adb, Android NDK lldb-server, host LLDB, and adb forward.
• Session state, generated LLDB command files, JSONL trace logs, and safe cleanup.
• Two LLDB Python control layers:
  • API mode when the host Python can import lldb.
  • CLI embedded Python fallback when only the lldb executable can run Python.
• Optional uv helper command for creating a Python venv and trying to expose NDK LLDB Python bindings.
• Legacy PowerShell and Bash scripts kept for compatibility and field reproduction.

Requirements

• Python 3.
• adb from Android SDK Platform Tools.
• Android NDK containing lldb-server.
• Host LLDB, usually from the same Android NDK toolchain.
• A connected Android device or emulator with USB debugging enabled.
• A debuggable target APK for run-as based workflows.
• Optional: uv, if you want to try a dedicated Python environment for external import lldb.

Main Commands

python scripts/android_lldb.py capabilities
python scripts/android_lldb.py python-env --ndk /path/to/android-ndk
python scripts/android_lldb.py check --package com.example.app
python scripts/android_lldb.py prepare --package com.example.app --port 5039
python scripts/android_lldb.py attach --package com.example.app --port 5039 --mode auto
python scripts/android_lldb.py trace --package com.example.app --breakpoint target_trace_point --output trace.jsonl
python scripts/android_lldb.py stop

uv Boundary

python-env can create a uv venv, link Android NDK LLDB Python paths through a .pth file, and validate:

python -c "import lldb"

This helps when external LLDB SB API mode is possible, but it does not replace native LLDB or liblldb. If validation fails, continue with --mode auto or --mode cli; CLI fallback runs Python inside the lldb executable through the embedded interpreter.

Documentation

• SKILL.md: agent-facing skill instructions.
• reference/LLDB_Report.md: LLDB API and scripted debugging model.
• reference/Android_NDK_Report.md: Android NDK, ABI, lldb-server, and remote debugging notes.
• reference/Python_Report.md: Python orchestration, subprocess, path, uv, and platform notes.
• reference/Field_Debugging_Report.md: real Windows + Android device validation notes.
• reference/lldb_python/: topic notes for official LLDB Python documentation.

Install As a Skill

For Codex, place this directory under:

$CODEX_HOME/skills/LldbAndroid

For Claude Code, place this directory under:

$CLAUDE_HOME/skills/LldbAndroid

For Cursor, reference this repository from project rules; Cursor does not have a Codex/Claude-style global skill runtime.