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/tiann/epic 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 3y ago

• 11 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Non-standard license (Other) — review terms

_{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 tiann/epic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tiann/epic.

What it runs against: a local clone of tiann/epic — 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 tiann/epic | 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 ≤ 1051 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tiann/epic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tiann/epic.git
#   cd epic
#
# 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 tiann/epic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tiann/epic(\\.git)?\\b" \\
  && ok "origin remote is tiann/epic" \\
  || miss "origin remote is not tiann/epic (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/src/main/java/me/weishu/epic/samples/MainApplication.java" \\
  && ok "app/src/main/java/me/weishu/epic/samples/MainApplication.java" \\
  || miss "missing critical file: app/src/main/java/me/weishu/epic/samples/MainApplication.java"
test -f "app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java" \\
  && ok "app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java" \\
  || miss "missing critical file: app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java"
test -f "app/src/main/java/me/weishu/epic/samples/tests/TestManager.java" \\
  && ok "app/src/main/java/me/weishu/epic/samples/tests/TestManager.java" \\
  || miss "missing critical file: app/src/main/java/me/weishu/epic/samples/tests/TestManager.java"
test -f "app/src/main/java/me/weishu/epic/samples/tests/custom/CaseManager.java" \\
  && ok "app/src/main/java/me/weishu/epic/samples/tests/custom/CaseManager.java" \\
  || miss "missing critical file: app/src/main/java/me/weishu/epic/samples/tests/custom/CaseManager.java"
test -f "app/src/main/java/me/weishu/epic/samples/MainActivity.java" \\
  && ok "app/src/main/java/me/weishu/epic/samples/MainActivity.java" \\
  || miss "missing critical file: app/src/main/java/me/weishu/epic/samples/MainActivity.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1051 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1021d)"
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/tiann/epic"
  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).

Epic is a dynamic Java method AOP (Aspect-Oriented Programming) hook framework for Android that intercepts and modifies method calls at runtime without bytecode rewriting. It's the ART-compatible successor to Dexposed, supporting Android 5.0–11, enabling non-invasive instrumentation of both app code and Android framework methods running in the same process through a single JNI library load. Mixed monorepo structure: app/ contains the sample Android application (MainActivity.java, test cases under app/src/main/java/me/weishu/epic/samples/tests/), while library/ (inferred from build.gradle) holds the core Epic AAR. Native code (C++/CMake) lives separately for JNI hooking bindings. Test cases in app/src/androidTest/ and elaborate argument-passing tests (ArgStatic*.java) validate calling conventions across architectures (armeabi-v7a, x86).

Android security researchers, penetration testers, and app developers who need to intercept framework APIs for instrumentation, performance monitoring, sensitive API auditing, and runtime AOP without rebuilding APKs. Contributors are typically low-level Android engineers familiar with ART runtime internals and native hooking.

Moderately mature but aging. The project is a direct continuation of Alibaba's Dexposed (2013–2015) ported to ART; README shows version 0.11.2 via jitpack, indicating slow-moving releases. No recent GitHub Actions CI runs visible in the file list, and the .github/workflows/android.yml suggests CI infrastructure exists but recency is unclear. Production-ready for supported Android versions (5.0–11) but not actively developed.

High risk for long-term maintenance: single-maintainer GitHub user (tiann) with minimal visible issue/PR activity, ART runtime compatibility is version-specific and brittle (Android 12+ may break), NDK code (35KB C++) requires platform experts to maintain, and no automated test suite visible beyond app/src/androidTest. The framework directly modifies running Java method bytecode via JNI, introducing crashes if incompatible with new ART versions.

No visible active development. The repository shows a stable snapshot state with no open PRs or recent commits listed. The last integration point visible is Android SDK 30 (compileSdkVersion), and the project structure suggests it's in maintenance mode, providing backward compatibility for existing users rather than pursuing new features.

Clone and build with Gradle:

git clone https://github.com/tiann/epic.git
cd epic
./gradlew build
./gradlew installDebug  # Install sample app to emulator/device

Minimum: Android API 21 (minSdkVersion in app/build.gradle), NDK must be configured in Android Studio.

Daily commands: Build and run instrumented tests:

./gradlew connectedAndroidTest  # Runs app/src/androidTest/ on device
./gradlew installDebug          # Deploys sample app
adb shell am start -n me.weishu.epic.samples/.MainActivity

No separate dev server; this is an Android library meant to be integrated into other APKs.

• app/src/main/java/me/weishu/epic/samples/MainApplication.java — Entry point where Epic AOP framework is initialized; all contributors must understand how the JNI library is loaded and framework setup occurs
• app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java — Core example demonstrating the method hooking callback pattern; essential for understanding how to intercept and wrap method execution
• app/src/main/java/me/weishu/epic/samples/tests/TestManager.java — Orchestrates all test cases and hook registration; shows how the framework is used in practice across different scenarios
• app/src/main/java/me/weishu/epic/samples/tests/custom/CaseManager.java — Manages custom test cases that exercise advanced hooking scenarios; demonstrates framework capabilities and edge cases
• app/src/main/java/me/weishu/epic/samples/MainActivity.java — UI entry point that displays test results; required to understand how the framework diagnostics surface to users
• app/build.gradle — Build configuration with NDK integration for native AOP implementation; critical for understanding compilation requirements

Add a New Method Hook Test Case

1. Create a new test class extending TestCase in app/src/main/java/me/weishu/epic/samples/tests/custom/ (app/src/main/java/me/weishu/epic/samples/tests/custom/Case18_returnConst.java)
2. Implement the target methods to be hooked as a nested class or companion class (app/src/main/java/me/weishu/epic/samples/tests/custom/Target.java)
3. Register the hook using the Epic API with MethodHook and override beforeCall/afterCall methods (app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java)
4. Add the new test case to CaseManager.buildCases() to integrate into the test suite (app/src/main/java/me/weishu/epic/samples/tests/custom/CaseManager.java)

Add a New Return Type Test

1. Create a new return type test class in app/src/main/java/me/weishu/epic/samples/tests/returntype/ (app/src/main/java/me/weishu/epic/samples/tests/returntype/StringType.java)
2. Implement the test method in the corresponding target class (app/src/main/java/me/weishu/epic/samples/tests/returntype/ReturnTypeTarget.java)
3. Hook the method and validate return value in beforeCall/afterCall (app/src/main/java/me/weishu/epic/samples/tests/LogMethodHook.java)
4. Register the test case in TestManager to expose in the UI test suite (app/src/main/java/me/weishu/epic/samples/tests/TestManager.java)

Add a New Argument Signature Test

1. Create a new static method test class extending AbsArgStaticCase following naming convention (e.g., ArgStaticXXXX.java) (app/src/main/java/me/weishu/epic/samples/tests/arguments/ArgStatic8888.java)
2. Add the corresponding target method to ArgumentTarget with matching parameter types (app/src/main/java/me/weishu/epic/samples/tests/arguments/ArgumentTarget.java)
3. Override getValue() and getExpected() to provide test values and assertions (app/src/main/java/me/weishu/epic/samples/tests/arguments/AbsArgStaticCase.java)
4. Register the test in TestManager.getArgumentTests() to enable in test suite (app/src/main/java/me/weishu/epic/samples/tests/TestManager.java)

• JNI (Java Native Interface) + NDK — Required to hook methods at the ART runtime level; native code can intercept method calls before/after execution on Android 5.0–11
• Android Gradle + NDK Build — Compiles native AOP hooking library (armeabi-v7a, x86) alongside Java code; integrates C/C++ runtime modifications
• Method Reflection & Callback Pattern — Allows dynamic interception of arbitrary Java methods without source code modification; enables non-invasive AOP
• Instrumented Android Tests — Validates framework functionality across diverse method signatures, return types, and calling conventions on real Android runtimes

• Native JNI-based hooking vs. bytecode instrumentation

  • Why: Bytecode modification would require recompiling APK; native hooking works post-compilation at runtime without repackaging
  • Consequence: Requires platform-specific NDK compilation and careful ART internals knowledge; offsets deployment simplicity

• Support Android 5.0–11 only vs. broad version compatibility

  • Why: ART runtime internals vary significantly across Android versions; supporting all would multiply code complexity exponentially
  • Consequence: Limited to modern devices; older KitKat and pre-5.0 devices unsupported; reduces maintenance burden

• Extensive test suite (100+ test cases) vs. minimal validation

  • Why: AOP hooking touches critical runtime paths; comprehensive tests catch edge cases (GC, JIT, fast native, constructor calls)
  • Consequence: Large test footprint increases validation confidence but adds maintenance overhead for new Android versions

• Does not provide static compile-time AOP (no annotation processors or bytecode rewriting)
• Does not support Android versions below 5.0 or pre-ART Dalvik runtime
• Does not replace system-level security policies or permission enforcement
• Does not provide IDE integration or source-level debugging for hooked methods
• Does not guarantee compatibility with obfuscated/ProGuard-processed code without explicit rules

1. ART version pinning: Hooking works via direct ART runtime bytecode modification; Android 12+ may have breaking changes not backported. 2) JNI stability: Calling convention tests (ArgStatic4844.java, etc.) exist because argument marshaling is fragile across ARM/x86/ARM64—test thoroughly when targeting new architectures. 3) No reflection guard: Framework methods hooked may be hidden APIs (android.*) subject to restrictions in API 28+; apps targeting API 31+ need proper API hiding workarounds. 4) Initialization timing: DexposedBridge must be loaded in MainApplication.onCreate() before any framework method call, or hooks miss early invocations.

• Aspect-Oriented Programming (AOP) — Epic's entire purpose is AOP—intercepting method calls to add cross-cutting concerns (logging, monitoring, security checks) without modifying source code; mastering AOP is essential to understand why Epic exists
• Java Method Hooking / Trampolines — Epic replaces target method bytecode with jumps to trampoline stubs that call user callbacks; understanding trampolines is critical for debugging hook failures and understanding performance overhead
• ART (Android Runtime) Internals — Epic directly modifies ART's in-memory method bytecode and interpreter state; knowing ART's method resolution, dispatch, and JIT compilation is mandatory for diagnosing version-specific breakage
• JNI (Java Native Interface) Calling Conventions — Epic uses JNI to bridge Java callbacks and native hooking code; the ArgStatic*.java test suite exists because ARM/x86 calling conventions differ, and Epic must correctly marshal arguments between Java and native stack frames
• Reflection and Runtime Type Discovery — DexposedBridge.findAndHookMethod() uses Java reflection to locate target methods by name/signature at runtime; Epic's entire API relies on runtime introspection rather than compile-time code generation
• Binary Compatibility and ABIs — Epic maintains separate native libraries for armeabi-v7a and x86 architectures; ABI differences in register allocation, stack layout, and calling conventions directly impact hook correctness, as evidenced by CallingConventationTest
• Method Resolution and Virtual Dispatch — Epic must understand how ART resolves virtual vs. static method calls, inheritance chains, and interface dispatch to correctly identify and intercept the right method; this affects hook placement and callback triggering

• alibaba/dexposed — Direct predecessor and inspiration; Epic is the ART port of Dexposed, which pioneered non-invasive AOP for Android
• rovo89/Xposed — Original Xposed framework that Dexposed/Epic's XC_MethodHook API derives from; system-level hooking for all processes
• android/android-ndk — Required for building Epic's C++ JNI code; defines NDK toolchain and ART runtime headers
• LSPosed/LSPosed — Modern successor to Xposed for Android 8+; uses similar hooking concepts but via Zygote injection instead of app-level JNI
• Yalantis/uCrop — Example of a library integrated via AAR (like Epic); shows typical Gradle dependency pattern for distributing Android hooked frameworks

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 instrumented tests for Android 11 (API 30+) compatibility

The README states Epic supports Android 5.0~11, but the app/src/androidTest directory only contains ExampleInstrumentedTest.java. Given that Epic is a low-level ART hooking framework supporting multiple Android versions, comprehensive instrumented tests verifying correct behavior on Android 11+ are critical. The existing test structure in app/src/main/java/me/weishu/epic/samples/tests (CallingConventationTest, argument variations, custom cases) should have corresponding instrumented test counterparts to validate AOP hook behavior across API levels.

• [ ] Create app/src/androidTest/java/me/weishu/epic/Android11CompatibilityTest.java to test hook behavior on API 30+
• [ ] Port CallingConventationTest logic to instrumented tests in app/src/androidTest
• [ ] Add instrumented tests for FastNative methods (Case13_FastNative.java) which have special ART handling
• [ ] Update .github/workflows/android.yml to run instrumented tests on multiple API levels (21, 28, 29, 30) in CI

Add unit tests for the native method hooking layer

The repo contains extensive native code (evidenced by externalNativeBuild/ndkBuild configuration targeting armeabi-v7a and x86), but there are no unit tests in the codebase validating the native hooking implementation. This is critical for a low-level AOP framework where native code correctness directly impacts all Java-level hooks. Add tests specifically for method resolution, ARM/x86 calling conventions, and hook installation/removal.

• [ ] Create library/src/test/cpp directory structure for native unit tests
• [ ] Write CMake/NDK tests validating method signature parsing and resolution
• [ ] Add tests for ARM (armeabi-v7a) and x86 calling convention handling in native code
• [ ] Integrate native tests into .github/workflows/android.yml CI pipeline

Document and test ProGuard/R8 obfuscation safety for hook targets

The app includes proguard-rules.pro but lacks documentation on how to safely configure ProGuard/R8 when using Epic hooks. Since Epic hooks methods by name/signature, obfuscation can break hooks if target classes/methods are renamed. Add comprehensive guidance and test cases validating that hooks survive ProGuard/R8 processing in release builds.

• [ ] Create app/proguard-rules.pro rules documenting which patterns to exclude from obfuscation when using Epic
• [ ] Add test case app/src/main/java/me/weishu/epic/samples/tests/ProGuardSafetyTest.java validating hooks work on obfuscated methods
• [ ] Add instrumented test verifying release build hooks (with minifyEnabled true) function correctly
• [ ] Document findings in README.md with a 'ProGuard Integration' section

• Add unit tests for XC_MethodHook parameter passing in app/src/androidTest/. Currently only CallingConventationTest.java exists; create parameterized tests validating thisObject, args[], and return value mutation across primitive types, objects, and null values.
• Document the exact ART bytecode modification mechanism: create a README_INTERNALS.md explaining how JNI intercepts method entry, rewrites opcodes, and manages trampoline stubs. Developers need to understand why Android 12+ broke hooks.
• Add support for API 31+ hidden method restrictions: wrap DexposedBridge.findAndHookMethod() to detect framework.jar methods and emit warnings or fallback to reflection for non-hidden alternatives. See TestManager.java for hook registration patterns.

The EPIC project has moderate security concerns primarily related to outdated dependencies, low minimum SDK version targeting, and disabled security features in the build configuration. As a method hooking framework, it has inherent security implications that require careful threat modeling. Key issues include: (1) QMUI 1.0.4 is severely outdated, (2) compilation against Android 11 is below modern standards, (3) support for Android 5.0 expands attack surface, (4) minifyEnabled is false reducing reverse-engineering

• High · Outdated Dependency - QMUI Library — app/build.gradle - dependencies section. The project uses QMUI library version 1.0.4, which is significantly outdated (released around 2018). This version likely contains known security vulnerabilities and lacks modern security patches. Fix: Update QMUI to the latest stable version. Run 'gradle dependencies' to identify known vulnerabilities and update to at least 1.4.x or newer.
• High · Compilation Target Version Below Modern Standards — app/build.gradle - android section. The project targets compileSdkVersion 30 (Android 11), which is outdated. Current standards recommend compileSdkVersion 34 (Android 14) or higher. This may miss security improvements and privacy features in newer Android versions. Fix: Update compileSdkVersion to 34 or higher, and targetSdkVersion to match. Test thoroughly for compatibility.
• Medium · Minimum SDK Version Too Low — app/build.gradle - defaultConfig section. minSdkVersion is set to 21 (Android 5.0), which is very old. Supporting such old versions exposes the app to known security vulnerabilities and outdated SSL/TLS implementations. Fix: Increase minSdkVersion to at least 24 (Android 7.0) or preferably 26+ to ensure modern security standards and reduce attack surface.
• Medium · ProGuard Configuration Not Enforced in Debug — app/build.gradle - buildTypes.release section. ProGuard/R8 obfuscation is disabled in release builds according to 'minifyEnabled false'. This reduces protection against reverse engineering and makes method hooking exploitation easier. Fix: Enable minifyEnabled true in release builds and configure proper ProGuard rules in proguard-rules.pro. Test thoroughly for functionality.
• Medium · Native Code via NDK Build — app/build.gradle - externalNativeBuild section. The project uses NDK with native code compilation for ARM and x86 architectures. Native code is particularly vulnerable to exploitation and requires careful security review. No visible security controls documented. Fix: Conduct thorough security review of native code in src/main/jni/. Implement code signing, disable debugging symbols in release builds, and use address space layout randomization (ASLR) compatible code.
• Medium · No Explicit Dependency Version Pinning — app/build.gradle - dependencies section. Dependencies use dynamic versions (e.g., 'implementation project(:library)' without version specification), which could allow unexpected updates that introduce vulnerabilities. Fix: Use explicit version numbers for all dependencies and implement dependency locking with gradle lockfile. Regularly audit dependencies with tools like gradle dependency-check.
• Low · Lint Errors Not Enforced — app/build.gradle - lintOptions section. The lintOptions configuration sets 'abortOnError false', meaning lint warnings and errors do not block builds. This could allow security issues to slip into production. Fix: Set abortOnError to true or handle specific lint issues individually. Address all security-related lint warnings before disabling.
• Low · Potential Xposed/Hook Exploitation Risk — Project architecture - library module. Epic is a dynamic method hooking framework that allows runtime AOP on Android. While this is the intended functionality, it presents a significant attack vector if compromised. The framework supports Android 5.0-11 and operates at the ART runtime level. Fix: Implement strong verification mechanisms for hook integrity. Use code signing, checksums, and implement anti-tampering measures. Document trusted sources for hooks and validate all hook sources.

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.