If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rovo89/Xposed shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 6y ago

• 8 active contributors
• Other licensed
• ⚠ Stale — last commit 6y ago
• ⚠ Single-maintainer risk — top contributor 87% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rovo89/Xposed repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rovo89/Xposed.

What it runs against: a local clone of rovo89/Xposed — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rovo89/Xposed | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 2191 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rovo89/Xposed. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rovo89/Xposed.git
#   cd Xposed
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rovo89/Xposed and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rovo89/Xposed(\\.git)?\\b" \\
  && ok "origin remote is rovo89/Xposed" \\
  || miss "origin remote is not rovo89/Xposed (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app_main.cpp" \\
  && ok "app_main.cpp" \\
  || miss "missing critical file: app_main.cpp"
test -f "libxposed_common.cpp" \\
  && ok "libxposed_common.cpp" \\
  || miss "missing critical file: libxposed_common.cpp"
test -f "xposed.h" \\
  && ok "xposed.h" \\
  || miss "missing critical file: xposed.h"
test -f "libxposed_art.cpp" \\
  && ok "libxposed_art.cpp" \\
  || miss "missing critical file: libxposed_art.cpp"
test -f "libxposed_dalvik.cpp" \\
  && ok "libxposed_dalvik.cpp" \\
  || miss "missing critical file: libxposed_dalvik.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2191 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2161d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rovo89/Xposed"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Xposed is a native Android framework modification system that hooks into the Dalvik/ART runtime to intercept and modify method calls at the Java level without modifying source APKs. This repo contains the core native binary (modified app_process) written in C++ that replaces the standard Android app launcher and injects the Xposed hooks into every running process, enabling runtime behavior modification through loadable modules. Monolithic native binary with dual-path support: app_main.cpp and app_main2.cpp provide version-specific entry points, libxposed_art.cpp and libxposed_dalvik.cpp contain runtime-specific hook implementations, and xposed_offsets.h stores hardcoded memory offsets per Android version. Core utilities (logging, service, safemode) are in dedicated modules. Built via Makefile with Android.mk for integration into AOSP build system.

Android developers and security researchers who need to dynamically modify app behavior at runtime without recompiling APKs, particularly those building development tools, testing frameworks, or security analysis modules. Xposed module developers use this to hook into system and third-party app methods for instrumentation, customization, or security research.

Actively maintained but with critical version constraints: the repo targets multiple Android versions (Dalvik through ART) with version-specific compilation paths (Dalvik.mk, ART.mk), but commit recency data is not visible in the provided metadata. The presence of safemode, logging, and service modules suggests production-grade implementation, though the single primary maintainer (rovo89) indicates potential single-point-of-failure risk. Not a typical open-source project with public issue trackers or CI visible.

High risk for end-user stability: this binary replaces the system app_process, so any crashes cause boot loops. Deep Android internals coupling via xposed_offsets.h requires manual offset updates for each Android version—breaking silently on ART JIT/AOT changes. Minimal visible test coverage in the file structure (no test/ directory apparent), and the app_main.cpp/app_main2.cpp split suggests version-specific brittle patches. Abandoned by Google's official support post-Android 9+, making it incompatible with modern Android versions.

Unable to determine from metadata provided—no git log, branch info, or active PR list is visible. The file structure suggests the project is stable/maintenance-phase given the presence of both Dalvik.mk and ART.mk support, but active development status is unclear.

Clone the repo and build via Android.mk within an AOSP source tree: git clone https://github.com/rovo89/Xposed && cd Xposed && mmm . -j4 (requires Android NDK/build environment). For standalone compilation, extract the relevant source files and use the provided Makefile with appropriate NDK paths configured.

Daily commands: This is not a runtime daemon but a replacement binary. Integration requires: (1) Replace system /system/bin/app_process with the compiled binary, (2) Xposed modules loaded via zygote hooks at process startup, (3) Typically deployed on rooted devices or custom ROMs. No standard 'run' command; it executes as the system app launcher.

• app_main.cpp — Primary entry point for the modified app_process binary that bootstraps the Xposed framework at application startup.
• libxposed_common.cpp — Core runtime logic shared across ART and Dalvik VMs; implements fundamental hooking and reflection mechanisms that all modules depend on.
• xposed.h — Central header defining the public API surface, data structures, and constants used throughout the framework.
• libxposed_art.cpp — ART runtime-specific implementation that handles hooking on modern Android versions; critical for API 21+ support.
• libxposed_dalvik.cpp — Dalvik runtime-specific hooking implementation for legacy Android; maintains backward compatibility.
• xposed_offsets.h — Runtime offset definitions for VM internals; any version mismatch here breaks the entire framework on that Android version.
• xposed_service.cpp — IPC service layer enabling communication between framework and Xposed modules; handles privileged operations.

Add Support for a New Android API Level

1. Research the target Android version's ART/Dalvik VM internal structure (method offsets, field layouts) (xposed_offsets.h)
2. Add new offset constants for the API level in the header file under appropriate #ifdef guards (xposed_offsets.h)
3. Review and extend ART hooking logic if bytecode format or method resolution changed (libxposed_art.cpp)
4. Test with a process using that API level and verify hooks fire correctly (xposed_logcat.cpp)
5. Update build configuration if VM layout or calling conventions differ (Android.mk)

Add a New Privileged Operation to the IPC Service

1. Define the new operation ID and request/response message structure in the service header (xposed_service.h)
2. Implement the operation handler in the service implementation, with permission checks (xposed_service.cpp)
3. Add logging for the operation invocation for debugging and security auditing (xposed_logcat.cpp)
4. Document the operation contract and verify modules can call it correctly

Implement a Hook for a New Target Method

1. Identify whether the method is in system framework or application code (libxposed_common.h)
2. Register the method reference and callback handler in the module's initialization function (libxposed_common.cpp)
3. Implement the hook callback logic (before/after replacement, parameter inspection) (libxposed_common.cpp)
4. Test hook execution order and parameter passing using logcat output (xposed_logcat.cpp)

Handle a Safe Mode Boot Scenario

1. Check safe mode flags during framework initialization (xposed_safemode.cpp)
2. Conditionally disable module loading and hooks if recovery is needed (libxposed_common.cpp)
3. Log the safe mode state transition for diagnostics (xposed_logcat.cpp)
4. Verify modules do not interfere with boot recovery process

• C++ with inline assembly — Direct VM internals manipulation requires low-level memory access and performance-critical offset calculations; Java would not provide sufficient control.
• Android NDK build system (Android.mk) — Native library compilation must integrate with the system ROM build pipeline and link against device-specific ART/Dalvik libraries.
• Binder IPC (xposed_service.cpp) — Android's standard inter-process communication mechanism ensures privilege isolation and compatibility with the security model.
• Compile-time offset definitions (xposed_offsets.h) — VM internal layouts are ABI-specific; baking offsets at build time allows per-device ROM customization without runtime discovery overhead.

• Separate ART and Dalvik implementations (libxposed_art.cpp vs libxposed_dalvik.cpp)

  • Why: ART (5.0+) and Dalvik (4.x) have fundamentally different method resolution, bytecode format, and memory layouts.
  • Consequence: Code duplication and maintenance burden; changes must be applied to both paths. Compensated by cleaner per-runtime logic.

• Offset-based VM patching rather than public API hooks

  • Why: No stable public API exists for method interception; must directly access private runtime structures.
  • Consequence: Framework is fragile across Android versions and ROM variants; requires per-build offset tuning but enables powerful capabilities.

• Module loading during zygote initialization (app_main.cpp)

  • Why: Hooking must occur before any application code runs to intercept framework method calls.
  • Consequence: Any module crash during init can break device boot; requires strict safe mode fallback (xposed_safemode.cpp).

• Single shared service instance (xposed_service.cpp) for all modules

  • Why: Reduces memory overhead and simplifies privilege management.
  • Consequence: Service bottleneck if many modules call simultaneously; requires careful request queuing and timeout handling.

• Does not provide its own module distribution or app store; modules must be installed separately.
• Does not implement privilege escalation; relies on pre-existing root/system access to install the modified app_process.
• Does not sandbox modules from each other or the system; a malicious module can compromise the entire framework.
• Does not provide versioning guarantees across Android releases; offsets must be rebuilt for each ROM version.
• Does not support modules written in Java; hooks are C++-only at the core level (though modules may expose Java interfaces).

Critical version-specific offsets in xposed_offsets.h must be manually maintained for each Android version—misaligned offsets cause silent method lookup failures or process crashes. The app_main.cpp/app_main2.cpp split suggests fragile version detection logic; incorrect version routing breaks all app launching. Building requires full AOSP environment (not standalone NDK), and incorrect Android version target in build flags silently produces non-functional binaries. No runtime version validation—binary built for Android 6.0 will crash on Android 8.0 without rebuild.

• Zygote Injection — Xposed hooks into the zygote process (Android's app fork server) at app_process startup to inject modules before any user code runs; understanding zygote lifecycle is essential to understanding when hooks are installed
• Runtime Method Hooking / AOP (Aspect-Oriented Programming) — The core technique of Xposed—intercepting method calls at runtime without recompilation—is a form of AOP; understanding this pattern helps explain how libxposed_art.cpp and libxposed_dalvik.cpp actually modify behavior
• Memory Offset-Based Patching — xposed_offsets.h relies on hardcoded memory structure offsets to locate and patch runtime functions; this is fragile but necessary since the Dalvik/ART source isn't exposed at runtime, requiring knowledge of binary layout
• Dalvik vs. ART Runtime — Xposed must support both the older Dalvik (pre-Android 5.0) and modern ART bytecode interpreters, which have completely different internal structures; this explains the dual libxposed_dalvik.cpp/libxposed_art.cpp implementations
• JIT/AOT Compilation Challenges — ART uses Just-In-Time and Ahead-Of-Time compilation; Xposed must hook before or during compilation, not after, or the hook is bypassed; this constraint explains many of the version-specific offsets and fragility
• SELinux Constraints on Custom Binaries — Replacing /system/bin/app_process requires disabling or custom SELinux policies; understanding SELinux contexts helps explain why Xposed only works on rooted/custom ROM devices
• Safemode / Fallback Boot Mechanisms — xposed_safemode.cpp prevents boot loops when module hooks crash; understanding recovery patterns is important for maintaining device stability when modifying system-critical processes

• wanam/XposedPlus — Fork/continuation of Xposed framework with ART support improvements and modern Android compatibility patches
• taichi-framework/TaiChi — Modern successor to Xposed that uses LSPosed injection mechanisms to work on Android 8+; solves the same module injection problem with different technical approach
• RikkaApps/Shizuku — Related root/privilege delegation framework often used alongside Xposed for inter-process privilege elevation in module ecosystems
• rovo89/XposedBridge — Java-side counterpart in the same organization; provides the public API that modules call, compiled into the Xposed framework package
• rovo89/XposedInstaller — Official manager APK that communicates with this native framework via xposed_service for module installation and system status

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive offset validation and documentation in xposed_offsets.h

The xposed_offsets.h file appears to contain critical offset definitions for hooking into Android runtime structures. This is a high-risk area where incorrect offsets cause runtime crashes. A new contributor could add: (1) per-offset documentation explaining what each offset points to, (2) validation macros to detect offset mismatches at runtime, (3) a mapping table showing Android API levels and corresponding offset values. This prevents silent failures and makes the codebase more maintainable across Android versions.

• [ ] Review xposed_offsets.h and identify all offset definitions and their purposes
• [ ] Create detailed comments for each offset with source references (e.g., which struct member, which Android API level)
• [ ] Add runtime validation checks in libxposed_art.cpp and libxposed_dalvik.cpp that warn or fail gracefully if offsets don't match expected memory patterns
• [ ] Create a supplementary OFFSETS.md documenting the offset discovery process and maintenance requirements

Refactor app_main.cpp and app_main2.cpp into modular initialization components

The app_main.cpp and app_main2.cpp files likely contain duplicated initialization logic for Dalvik vs ART runtimes. This is a perfect refactoring opportunity. Extract common initialization code into reusable functions in a new file (e.g., app_init_common.cpp), then have both app_main variants call these functions with runtime-specific callbacks. This reduces code duplication, lowers maintenance burden, and makes adding support for new Android versions easier.

• [ ] Analyze app_main.cpp and app_main2.cpp to identify common initialization patterns
• [ ] Create app_init_common.cpp with extracted common initialization logic
• [ ] Define callback interfaces for runtime-specific operations (ART vs Dalvik)
• [ ] Update both app_main.cpp and app_main2.cpp to use the new common initialization layer
• [ ] Add comments explaining the initialization flow and callback contract

Add unit tests for xposed_service.cpp message handling and xposed_safemode.cpp activation logic

Critical service communication and safemode detection code currently lacks visible test coverage. Create a test harness that: (1) mocks the Binder service interface to test message parsing in xposed_service.cpp, (2) tests safemode detection logic in xposed_safemode.cpp with various system property combinations, (3) validates that hook enable/disable commands are processed correctly. This catches regressions early and documents expected behavior.

• [ ] Review xposed_service.cpp to understand message protocol and command handling
• [ ] Review xposed_safemode.cpp to identify all system property checks and decision points
• [ ] Create tests/ directory structure with CMakeLists.txt or Android.mk for test compilation
• [ ] Write mock Binder interfaces for testing service commands without actual Binder IPC
• [ ] Write parametrized tests for safemode detection covering all property combinations
• [ ] Document test execution in README (e.g., 'mm test_xposed' or similar build target)

• Add unit tests for xposed_logcat.cpp: the logging module lacks test coverage; writing tests for log formatting and rotation would improve reliability and serve as good codebase entry
• Document xposed_offsets.h format and update procedure: create a guide explaining how to extract offsets for new Android versions (e.g., via aosp-grep scripts), as this is the most brittle part of maintenance
• Extend xposed_service.cpp with error callbacks: currently minimal error reporting to the Xposed manager APK; adding structured error codes and callbacks would improve debuggability for module developers

• High · Native Code Security - Memory Safety Risks — libxposed_art.cpp, libxposed_dalvik.cpp, app_main.cpp, app_main2.cpp. The codebase consists primarily of C++ native code (libxposed_.cpp, app_main.cpp) that directly interfaces with Android runtime. Without visible bounds checking, buffer overflow protections, or memory safety patterns, there is inherent risk of memory corruption vulnerabilities (buffer overflows, use-after-free, heap corruption). Fix: Implement comprehensive bounds checking, use safe string handling functions (strlcpy instead of strcpy), enable compiler protections (ASLR, DEP/NX, stack canaries), and conduct thorough code review and fuzzing of native code paths.
• High · Framework-Level Code Injection - Xposed Hook Architecture — libxposed_common.cpp, libxposed_common.h, xposed.cpp, xposed_service.cpp. As a framework that modifies app_process and injects code into running Android applications, Xposed is inherently vulnerable to being abused for malicious code injection if the module loading/verification mechanisms are weak. No visible cryptographic signature verification or module validation is evident in the file structure. Fix: Implement strong module verification: cryptographic signatures on all loaded modules, manifest validation, sandboxing of module execution, and permission-based access controls. Document and enforce secure module development practices.
• High · Privilege Escalation Risk — xposed_service.cpp, xposed_service.h. This framework operates at the system/root level to patch the runtime. Improper access controls or validation could allow unprivileged processes to invoke privileged operations through xposed_service or other IPC mechanisms. Fix: Implement strict permission checks for all service operations, validate caller identity and UID before any privileged operation, use SELinux policies to restrict access, and implement rate limiting and audit logging.
• Medium · Offset Hardcoding - ABI Fragility — xposed_offsets.h. The file 'xposed_offsets.h' suggests hardcoded offsets into Android runtime structures. These offsets are device/ROM/Android-version specific and can break compatibility or cause crashes. They also represent a maintenance burden and potential vector for exploitation if incorrect. Fix: Implement dynamic offset discovery at runtime rather than hardcoding. Use symbol resolution APIs, maintain comprehensive offset databases with versioning, and add runtime validation of offset correctness before use.
• Medium · Logging Information Disclosure — xposed_logcat.cpp, xposed_logcat.h. The xposed_logcat.cpp module handles logging. Improper filtering or excessive logging in production could leak sensitive information (function arguments, memory contents, internal state) to system logs accessible by multiple processes. Fix: Implement strict logging levels with production defaults to ERROR only, sanitize all logged data to remove sensitive information, implement access controls on log output, and add configuration options to disable detailed logging.
• Medium · Safe Mode Bypass Risk — xposed_safemode.cpp, xposed_safemode.h. The xposed_safemode module exists but without reviewing its implementation, it's unclear if safe mode activation can be reliably enforced or bypassed. Weak safe mode could allow persistent malicious hooks. Fix: Ensure safe mode is enforced at the earliest boot stages, implement hardware-backed verification if possible, disable all hooks in safe mode, use SELinux to prevent hook reinstatement, and implement tamper detection.
• Medium · Lack of Input Validation Documentation — xposed_service.cpp, libxposed_common.cpp. No visible input validation patterns in file names or structure. IPC operations and system service interactions likely accept untrusted input without clear validation. Fix: Implement strict input validation for all external inputs, use whitelisting rather than blacklisting, validate size/format/ranges of all parameters, implement comprehensive error handling, and add input fuzzing to test suite.
• Low · Missing Security Headers/Documentation — Repository root. No visible security.md, SECURITY.txt, or security policy documentation for vulnerability disclosure or security best practices for framework users. Fix: Create SECURITY.md with vulnerability disclosure policy, security contact information, and known limitations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.