NDKTrace

NDKTraceSkills is a local toolchain for Android native crash restoration and AI-assisted analysis. The recommended workflow is a project-aware agent skill that runs a deterministic C++ CLI first and falls back to guided workspace inspection only when project resolution is incomplete. The repository is organized around three primary parts:

• a C++ CLI in cli/
• a shared core library in cli/ that includes crash artifact parsing and symbolization helpers
• a Codex skill in skills/android-native-crash-analysis/

The current scaffold already includes a buildable CLI, project-aware Android resolution, and a local skill workflow that can fall back to workspace inspection when project resolution is incomplete.

Repository Layout

• cli/ contains the CMake-based C++ command-line application
• skills/android-native-crash-analysis/ contains the Codex skill
• docs/ contains the project notes and contracts

Documentation

• Documentation index
• Architecture overview
• CLI guide
• Skill guide

Current Scope

• Define the CLI command surface and JSON output contract, including artifact, frame, and memory-map metadata fields
• Keep crash artifact parsing in the shared core library instead of the CLI entry point
• Prefer verified ELF BuildId matches before path or basename fallback when selecting local symbol files
• Normalize logcat-wrapped native crash lines before frame parsing so raw logcat excerpts can be restored directly
• Let the CLI resolve Android project metadata, module selection, NDK paths, and preferred unstripped symbols when explicit paths are missing
• Let the local analysis skill call the CLI first and use workspace inspection only when the CLI reports partial or ambiguous project resolution
• Keep deterministic stack restoration, validation, and BuildId-aware matching in the CLI

Recommended Local Workflow

• provide the crash text plus either explicit ndk_path and symbol_path values or an Android project_path
• let the skill call ndktrace-cli resolve-project first to resolve the module, variant, ABI, NDK path, and preferred unstripped .so
• use skill-driven workspace inspection only when resolve-project returns partial, ambiguous, or not_found
• run ndktrace-cli validate before stack restoration when the selected native inputs are uncertain
• run ndktrace-cli restore only after the skill has selected concrete local paths

Quick Start

Build the CLI:

cmake -S cli -B cli/build
cmake --build cli/build --config Debug

Run the scanner:

cli\build\Debug\ndktrace-cli.exe scan-ndk --pretty

Resolve an Android project directly from a crash artifact:

cli\build\Debug\ndktrace-cli.exe resolve-project --project D:\Project\Android --stack-file crash.txt --pretty

Run the CLI tests:

ctest --test-dir cli/build -C Debug --output-on-failure