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/Tencent/matrix 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 2y ago

• 10 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• Other licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows 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 Tencent/matrix repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/matrix.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tencent/matrix(\\.git)?\\b" \\
  && ok "origin remote is Tencent/matrix" \\
  || miss "origin remote is not Tencent/matrix (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 "matrix/matrix-android/build.gradle" \\
  && ok "matrix/matrix-android/build.gradle" \\
  || miss "missing critical file: matrix/matrix-android/build.gradle"
test -f "matrix/matrix-android/matrix-android-commons/build.gradle" \\
  && ok "matrix/matrix-android/matrix-android-commons/build.gradle" \\
  || miss "missing critical file: matrix/matrix-android/matrix-android-commons/build.gradle"
test -f "matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c" \\
  && ok "matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c" \\
  || miss "missing critical file: matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c"
test -f "matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_elf.c" \\
  && ok "matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_elf.c" \\
  || miss "missing critical file: matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_elf.c"
test -f "matrix/matrix-android/matrix-android-commons/CMakeLists.txt" \\
  && ok "matrix/matrix-android/matrix-android-commons/CMakeLists.txt" \\
  || miss "missing critical file: matrix/matrix-android/matrix-android-commons/CMakeLists.txt"

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

Matrix is a non-invasive APM (Application Performance Management) system developed by WeChat that monitors crash, lag (jank), and memory issues across iOS/macOS and Android platforms. It uses a plugin architecture to hook into app lifecycle and thread/memory events without requiring code modifications, capturing detailed stack traces and performance metrics in production. Dual-platform monorepo: matrix/matrix-android/ contains Gradle-based Android modules (resource-canary, trace-canary, apk-checker plugins); matrix/matrix-iOS/ contains Xcode project with static frameworks (WCCrashBlockMonitorPlugin, WCMemoryStatPlugin, WCFPSMonitorPlugin). Native C/C++ code (~6M LOC) compiled via CMake, linked through JNI and Objective-C++ bridging.

Mobile app developers and performance engineers at scale who need to diagnose production crashes, UI lag, and memory exhaustion in WeChat-scale applications. Specifically: Android/iOS teams adopting WeChat's proven APM approach, and contributors familiar with JNI, runtime instrumentation, and cross-platform C++/Kotlin/Objective-C++ systems.

Highly mature and production-proven. Actively developed by Tencent/WeChat (badged v2.1.0+ on README), with comprehensive CI via CircleCI, multi-language test coverage (Java/Kotlin/C++/Objective-C), and dated open-source public disclosure (assets mention '开源公告'). Last visible activity shows ongoing gradle/buildtools modernization (gradle 4.1.0, compileSdkVersion 31).

Low risk for a mature WeChat-internal tool, but monorepo complexity is high: 3+ major codebases (Android ~3.1M Java, iOS ~344k Objective-C++, native ~3.1M C++) require separate build chains and tooling expertise. Dependencies on KSCrash (iOS), Kotlin 1.4.32, and custom gradle plugins; requires local.properties signing config that may not be obvious on first clone.

Gradle build system is being actively maintained (gradle 4.1.0, Android plugin updates visible). iOS/macOS builds via Makefile targets for build_ios/build_macos. CircleCI config present for automated testing. Documentation and issue templates exist but specific PR/milestone data not visible in provided metadata.

Android: cd matrix/matrix-android && ./gradlew build (requires local.properties with signing keys). iOS/macOS: cd matrix/matrix-iOS && make (generates frameworks in build_ios/ and build_macos/). Gradle 4.1.0, Kotlin 1.4.32, CMake, XCode 12+ required.

Daily commands: Android dev: cd matrix/matrix-android && ./gradlew :matrix-android-sample:assemble (builds sample app). iOS dev: cd matrix/matrix-iOS && make then link built Matrix.framework to Xcode project. Native testing: Requires CMake 3.x, clang/gcc for C++ compilation.

• matrix/matrix-android/build.gradle — Root Android build configuration defining Kotlin version, Gradle plugins, and repository setup for all modules
• matrix/matrix-android/matrix-android-commons/build.gradle — Commons library build config where native C++ modules (xhook, semi_dlfcn, libenhance_dlsym) are integrated via CMake
• matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c — Core hooking engine implementation—the foundation of Matrix's function interception capability for native monitoring
• matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_elf.c — ELF binary parsing for dylib resolution, critical to xhook's ability to locate and patch native symbols
• matrix/matrix-android/matrix-android-commons/CMakeLists.txt — CMake orchestration defining how native libraries (xhook, semi_dlfcn, enhance_dlsym) are compiled and linked
• matrix/matrix-android/gradle.properties — Global Gradle properties and version constants used across all Android submodules
• .github/issue_template.md — Contribution template documenting expected issue format and baseline for developer onboarding

Add a New Native Hook Target

1. Define the hook signature and callback in xh_core.h with xhook_register() macro (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.h)
2. Implement the hook handler in xh_core.c's hook dispatch table, adding logic to capture metrics (e.g., memory allocation size, call stack) (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c)
3. Export the hook registration function via xh_jni.c JNI bindings so Java plugins can activate it (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_jni.c)
4. Create a new Plugin subclass in matrix-android/matrix-*-plugin that calls the JNI hook registration at startup and processes metrics asynchronously

Add Support for a New ARM Architecture

1. Update CMakeLists.txt to define new ABI target and conditionally compile arch-specific xhook trampoline code (matrix/matrix-android/matrix-android-commons/CMakeLists.txt)
2. Extend xh_elf.c's ELF relocation logic to handle the new architecture's PLT/GOT layout and instruction encoding (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_elf.c)
3. Add inline assembly trampolines in xh_core.c for the new architecture (e.g., arm64-v8a register conventions, branch offsets) (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_core.c)
4. Test ELF parsing on the target architecture by running xh_maps.c tests and verifying symbol resolution (matrix/matrix-android/matrix-android-commons/src/main/cpp/libxhook/xh_maps.c)

Publish a New Matrix Module to Maven Central

1. Define module version and group ID in matrix/matrix-android/gradle.properties (matrix/matrix-android/gradle.properties)
2. Create module-level build.gradle applying android-publish.gradle with artifact metadata (name, description, license) (matrix/matrix-android/gradle/android-publish.gradle)
3. Configure signing credentials in local.properties (keystore path, password, alias) referenced by WeChatPublish.gradle (matrix/matrix-android/gradle/WeChatPublish.gradle)
4. Run ./gradlew publish to upload signed AAR and POM to Maven Central staging repository, then promote via web UI

• Native C++ (xhook) instead of Java reflection — Zero-copy, ultra-low-latency function interception; enables monitoring of libc/native layer (malloc, pthread, OpenGL) where 90% of performance bottlenecks occur in mobile apps
• ELF binary patching (PLT/GOT) instead of LD_PRELOAD or syscall interception — Works in production APKs without recompilation; avoids permission escalation and kernel interactions; fine-grained control over exactly which symbols are hooked
• Gradle multi-module + CMake build — Separates Java plugins from native instrumentation; allows parallel compilation of 3+ native libraries; integrates with Android Studio and CI/CD pipelines
• Ring buffer + async flush pattern — Bounded memory footprint during high-frequency events (frame callbacks, allocations); non-blocking writes to disk; avoids dropped events

• Plugin-style architecture with compile-time opt-in vs. always-on monitoring

  • Why: Developers ship only the monitoring modules they need (crash, lag, or memory); reduces APK size and runtime overhead for teams not using all features
  • Consequence: Slight complexity in plugin initialization; each plugin is independently testable but must coordinate via shared Matrix framework

• Non-invasive hooking (no source code modification) vs. instrumentation at build time

  • Why: Works with third-party libraries and binaries already compiled; can be added to existing apps with zero source changes
  • Consequence: Hook installation happens at runtime; requires careful thread-safety and memory management in xhook core; incompatible with code signing verification on some Android versions

• Batch buffering + periodic flush vs. immediate per-event logging

  • Why: Reduces I/O and garbage allocation by 100–1000x; enables statistical analysis (percentiles, histograms) instead of raw traces
  • Consequence: Recent events may be lost if app crashes before buffer flush; requires replay/state recovery logic for critical traces

• Real-time event streaming to a remote backend (batches to disk; backend upload is app's responsibility)
• Source-level code instrumentation or bytecode rewriting (only native function hooking)
• Network traffic inspection or request/response logging (APM scope is process-local metrics only)
• Android <5.0 support (relies on ELF64, PIE, and modern bionic)
• iOS/macOS development for this Android fork (separate matrix-ios codebase)

Android: local.properties must define REPOSITORY_USERNAME, REPOSITORY_PASSWORD, signing.keyId, signing.password, signing.secretKeyRingFile for publication (build will hang if missing). MIN_SDK_VERSION_FOR_HOOK = 21 required for full hook instrumentation; minSdkVersion = 19 supported but with reduced features. Gradle 4.1.0 is pinned and older than modern Android Studio defaults—update may break. iOS/macOS: Makefile build depends on xcode-select; KSCrash framework must be vendored or CocoaPods installed (matrix-wechat.podspec present but setup not obvious). General: Yacc-generated parser (39k LOC) in build chain—requires bison/flex if rebuilding. CircleCI config hints at missing local test running docs.

• Looper Instrumentation (Android ANR Detection) — Matrix detects lag by hooking into Android's Looper message loop idle/busy transitions; understanding this is essential to grasp how trace-canary identifies jank without blocking the main thread
• Stack Unwinding & Frame Pointers — Core native capability in matrix/libmatrix: fast async-safe stack capture during ANR/OOM requires reading frame pointers or DWARF unwind info; critical for low-overhead profiling
• Plugin Architecture (Non-Invasive Instrumentation) — Matrix's design is built on plugin interfaces that hook into app lifecycle without code changes; understanding PluginListener, Matrix.getInstance() registry, and lifecycle callbacks is foundational
• KSCrash Framework (iOS Crash Reporting) — iOS's WCCrashBlockMonitorPlugin builds on KSCrash's low-level Mach exception handling and memory introspection; critical for understanding iOS crash capture flow
• JNI/Java Native Interface Bridging — Matrix spans Java/Kotlin (Android app logic) and C++ (native hooks); JNI layer in libmatrix bridges these, requiring careful memory management and thread safety
• Runloop Monitoring (iOS Main Thread Detection) — iOS lag detection (WCCrashBlockMonitorPlugin) uses CFRunLoop observer callbacks to detect main thread stalls; more direct than Android's Looper but same concept
• Memory Allocation Profiling (Hooking malloc/new) — WCMemoryStatPlugin and resource-canary hook memory allocators to track live object callstacks; requires interposing malloc/new and storing metadata in O(1) overhead

• facebook/profilo — Similar Android profiling/tracing APM with native stack sampling and time-series metrics; alternative approach to lag detection
• google/perfetto — System-wide tracing infrastructure (Linux/Android kernel ftrace) that Matrix's native code could leverage for lower-overhead memory/CPU capture
• kstenerud/KSCrash — Foundation library for Matrix's iOS crash capture; Matrix wraps and extends KSCrash with runloop lag detection
• square/leakcanary — Android memory leak detection (object allocation tracking) solving similar OOM-prevention problem; Matrix's resource-canary is WeChat's alternative with production tuning
• uber/RIBs — Complementary WeChat-inspired architecture (plugin-based DI) that could integrate Matrix monitoring; represents ecosystem app structure that benefits from APM

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 GitHub Actions workflow for Android CI/CD validation

The repo currently uses CircleCI (.circleci/config.yml) but lacks GitHub Actions workflows. Adding native GitHub Actions would provide faster feedback on PRs without external dependencies, and improve visibility for contributors using GitHub's interface. This is especially valuable for a multi-platform project (Android/iOS/macOS) where different platforms need different build steps.

• [ ] Create .github/workflows/android-build.yml to run gradle build and tests for matrix-android/
• [ ] Create .github/workflows/android-lint.yml to run checkstyle (matrix-android/checkstyle.xml) and findbugs (matrix-android/findbugs-exclude.xml) validation
• [ ] Add step to verify Javadoc generation succeeds (currently disabled in build.gradle with TODO comment)
• [ ] Document in CONTRIBUTING.md how to run these checks locally before pushing

Add comprehensive unit tests for APM plugin framework core classes

The file structure shows extensive APM functionality (trace-canary, resource-canary, apk-checker plugins) but no visible test directories in matrix/matrix-android/. Adding unit tests for the plugin initialization and listener patterns shown in assets/img/readme would improve code reliability and serve as executable documentation for how to use the framework.

• [ ] Create matrix/matrix-android/matrix-core/src/test/ directory structure mirroring src/main/
• [ ] Write unit tests for plugin initialization flow (referenced in assets/img/readme/plugin-listener.png)
• [ ] Add tests for MatrixBuilder and configuration loading from local.properties pattern used throughout build.gradle
• [ ] Write tests for the non-invasive instrumentation approach used by trace-canary (document in test class)

Create iOS/macOS build validation GitHub Actions workflow

The repo supports iOS and macOS (evidenced by matrix-wechat.podspec, assets/开源公告-iOS.md, and wiki images for iOS), but there's no visible iOS-specific CI configuration beyond CircleCI. Adding GitHub Actions for CocoaPods validation and iOS SDK compilation would catch iOS-specific regressions earlier and reduce friction for iOS contributors.

• [ ] Create .github/workflows/ios-build.yml to validate matrix-wechat.podspec with pod lib lint
• [ ] Add step to build iOS project with xcodebuild targeting Matrix.xcodeproj
• [ ] Include CocoaPods dependency resolution and version compatibility checks
• [ ] Document iOS development setup in CONTRIBUTING.md with reference to .github/workflows configuration

• Add unit tests for the APK checker task result serialization in matrix/matrix-android/apk-checker/src/main/java/com/tencent/matrix/apk (file structure exists but test coverage unclear from file list)
• Document the JNI bridge layer between Java TracePlugin and native stack unwinding in matrix/matrix-android/libmatrix/src/main/cpp—add example of adding a new hook point
• Create quick-start example app in matrix/matrix-android/samples/ that demonstrates all three plugins (trace-canary, resource-canary, apk-checker) with minimal boilerplate and annotated output

• High · Outdated Gradle Build Plugin — build.gradle - buildscript dependencies. The build.gradle file uses com.android.tools.build:gradle:4.1.0, which is significantly outdated (released in 2020). This version may contain known security vulnerabilities and does not receive security updates. Current stable versions are 8.x and 7.x. Fix: Update to the latest stable version of the Android Gradle plugin (minimum 7.4.x, recommended 8.x). Run 'gradle wrapper --gradle-version <version>' to update.
• High · Outdated Kotlin Plugin — build.gradle - gradle.ext.KOTLIN_VERSION. Kotlin version 1.4.32 is outdated (released in 2021) and likely contains unpatched security vulnerabilities. Current stable versions are 1.9.x and 2.x. This affects the entire build toolchain. Fix: Update Kotlin to the latest stable version (1.9.20+ or 2.0+). Test thoroughly for compatibility before deploying to production.
• High · Hardcoded Local Properties Loading Without Validation — build.gradle - localProperties.load() section. The build script loads sensitive signing credentials from local.properties without verifying file existence or validating property contents. If local.properties is accidentally committed to version control, credentials could be exposed. The code uses newDataInputStream() which may not handle missing files gracefully. Fix: Implement proper file validation, use environment variables for sensitive data instead of properties files, and ensure local.properties is in .gitignore. Add existence checks before loading: if (project.rootProject.file('local.properties').exists())
• Medium · Missing Input Validation in SigningFromLocalProperties Function — build.gradle - SigningFromLocalProperties() function. The SigningFromLocalProperties function does not validate property values before assigning them to project extensions. Malformed or malicious values could be injected through local.properties. Fix: Add validation for sensitive properties (keyId, password, secretKeyRingFile paths). Implement checks for file path traversal, empty values, and expected format before assignment.
• Medium · Overly Permissive Target SDK Version — build.gradle - targetSdkVersion = 29. targetSdkVersion is set to 29, which is several versions behind the current Android target (35+). This means the app may not comply with current Google Play requirements and misses important security and privacy updates. Fix: Update targetSdkVersion to the latest stable version (34 or higher). Review and implement required permissions and privacy features for higher API levels.
• Medium · Low Minimum SDK Version — build.gradle - minSdkVersion = 19. minSdkVersion is set to 19 (Android 4.4, released 2013), which is extremely outdated. This exposes the application to devices with unpatched security vulnerabilities and requires maintaining compatibility with obsolete Android versions. Fix: Increase minSdkVersion to at least 24 (Android 7.0) or higher. This removes support for devices with known critical vulnerabilities while simplifying security maintenance.
• Medium · Outdated Build Tools Version — build.gradle - buildToolsVersion = '29.0.2'. buildToolsVersion '29.0.2' is outdated (released in 2019). Current recommended versions are 34.0.x and higher. Outdated build tools may lack security fixes and features. Fix: Update buildToolsVersion to 34.0.0 or the latest available stable version compatible with your target SDK.
• Low · Javadoc Generation Disabled Without Documentation — build.gradle - tasks.withType(Javadoc).all { enabled = false }. Javadoc is disabled with a TODO comment and no explanation. While not a security vulnerability directly, lack of documentation can lead to misuse of APIs and security issues in dependent code. Fix: Re-enable Javadoc or document the reason for disabling it. Ensure API security implications are documented for library users.
• Low · Missing Checksum Verification for Dependencies — undefined. The Fix: undefined

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.