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/markzhai/AndroidPerformanceMonitor 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
• Apache-2.0 licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits
• ⚠ 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 markzhai/AndroidPerformanceMonitor repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/markzhai/AndroidPerformanceMonitor.

What it runs against: a local clone of markzhai/AndroidPerformanceMonitor — 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 markzhai/AndroidPerformanceMonitor | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 1058 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/LooperMonitor.java" \\
  && ok "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/LooperMonitor.java" \\
  || miss "missing critical file: blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/LooperMonitor.java"
test -f "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryInternals.java" \\
  && ok "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryInternals.java" \\
  || miss "missing critical file: blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryInternals.java"
test -f "blockcanary-android/src/main/java/com/github/moduth/blockcanary/BlockCanary.java" \\
  && ok "blockcanary-android/src/main/java/com/github/moduth/blockcanary/BlockCanary.java" \\
  || miss "missing critical file: blockcanary-android/src/main/java/com/github/moduth/blockcanary/BlockCanary.java"
test -f "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java" \\
  && ok "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java" \\
  || miss "missing critical file: blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java"
test -f "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/internal/BlockInfo.java" \\
  && ok "blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/internal/BlockInfo.java" \\
  || miss "missing critical file: blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/internal/BlockInfo.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 1058 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1028d)"
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/markzhai/AndroidPerformanceMonitor"
  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).

BlockCanary is a transparent UI-block (jank) detection library for Android that automatically monitors the main Looper's message processing latency and captures stack traces when frames exceed a configurable threshold (typically 16ms). It requires only one line of code to install and automatically surfaces ANR-like events via system notifications without requiring code instrumentation or manifest changes. Gradle multi-module structure: blockcanary-analyzer contains core monitoring logic (LooperMonitor, StackSampler, CpuSampler, BlockInfo), blockcanary-android wraps UI/notification delivery (not shown but inferred from README), and blockcanary-android-no-op provides a compile-time stub for release builds. All code lives in com.github.moduth.blockcanary.* package hierarchy.

Android app developers (especially at startups and mid-size companies) who need to detect and debug UI jank caused by main-thread blocking operations in production or staging builds without the overhead of LeakCanary-style memory profiling.

Moderately mature but aging: the project has real adoption (Maven Central distribution, 4k+ stars historically), but the latest commit visible is from 2016-era versioning (1.5.0 with context/interceptor features), suggesting ~7+ year dormancy. No CI/CD files visible (no .travis.yml, gradle-mvn-push.gradle suggests manual publishing). Documentation is complete but version-pinned.

Single-maintainer project (markzhai) with no visible recent commits or test suite structure in the file list—risky for long-term maintenance. Dependency risk is low (minimal external deps, mostly stdlib), but Android API evolution (Looper internals, notification channels post-Android 8) may require updates. No breaking-changes log beyond CHANGELOG.md entries for versions 1.3–1.5.

No active development visible; the repo appears dormant. Version 1.5.0 (visible in README) added debug-mode context stopping and interceptor callbacks, but no further commits, PRs, or issues tracking are evident in the file structure provided.

git clone https://github.com/markzhai/AndroidPerformanceMonitor.git
cd AndroidPerformanceMonitor
./gradlew build

(Gradle wrapper detected; Java 7+ and Android SDK required per implicit gradle.properties).

Daily commands: This is a library, not an app. To test: integrate into an Android project's Application.onCreate() as shown in README: BlockCanary.install(context, new AppBlockCanaryContext()).start(); then trigger main-thread blocks (sleep, loops, I/O) to see notifications.

• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/LooperMonitor.java — Core monitoring engine that hooks into Android's Looper to detect UI blocks by sampling stack traces and CPU usage
• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryInternals.java — Central orchestrator that manages initialization, lifecycle, and coordination between samplers and interceptors
• blockcanary-android/src/main/java/com/github/moduth/blockcanary/BlockCanary.java — Public API entry point for one-line initialization and configuration in production apps
• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java — Configuration interface defining sampling thresholds, white-lists, interceptors, and notification handlers
• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/internal/BlockInfo.java — Data model encapsulating detected block event with stack traces, CPU metrics, and timing information
• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/StackSampler.java — Periodic sampler that captures main thread stack traces during suspected blocks for analysis
• blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/CpuSampler.java — System-level sampler that measures CPU usage to correlate with UI blocks and determine intensity

Add a Custom Context with Application-Specific Configuration

1. Create a new class extending BlockCanaryContext in your app module (blockcanary-sample/src/main/java/com/example/blockcanary/AppContext.java)
2. Override getThresholdMillis() to set block detection threshold, typically 500–1000ms (blockcanary-sample/src/main/java/com/example/blockcanary/AppContext.java)
3. Override getWhiteList() to exclude known heavy operations from flagging (blockcanary-sample/src/main/java/com/example/blockcanary/AppContext.java)
4. Initialize in Application.onCreate() with BlockCanary.install(this, new AppContext()) (blockcanary-sample/src/main/java/com/example/blockcanary/DemoApplication.java)

Integrate Block Event Upload to Backend Analytics

1. Override onBlockEvent(BlockInfo) in your BlockCanaryContext subclass (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java)
2. Instantiate Uploader or custom mechanism to send BlockInfo to your analytics service (blockcanary-android/src/main/java/com/github/moduth/blockcanary/Uploader.java)
3. Include block duration, stack traces, and CPU metrics in the upload payload (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/internal/BlockInfo.java)

Filter or Modify Detected Blocks with Custom Interceptor

1. Implement BlockInterceptor interface in your application (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockInterceptor.java)
2. Override onBlock() to inspect BlockInfo and return true to suppress notification if desired (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockInterceptor.java)
3. Register interceptor via BlockCanaryContext.getInterceptor() (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryContext.java)

Create a Custom Sampler for Application-Specific Metrics

1. Extend AbstractSampler in blockcanary-analyzer module (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/AbstractSampler.java)
2. Implement doSample() to collect your custom metric during block events (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/AbstractSampler.java)
3. Register sampler in BlockCanaryInternals.start() or via BlockCanaryContext hook (blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/BlockCanaryInternals.java)

• Looper.Printer hook — Only non-invasive way to measure main thread dispatch timing without modifying framework code; receives dispatchStart/dispatchEnd callbacks
• Background sampling threads (StackSampler, CpuSampler) — Avoids blocking the main thread during metrics collection; captures call stacks and system CPU state at regular intervals
• No-op variant library (blockcanary-android-no-op) — Eliminates monitoring overhead in release builds via build-type dependency; maintains identical API surface
• LeakCanary-inspired UI — Familiar visual paradigm for Android developers; DisplayActivity provides offline browsing of block history without dependency on crash reporting
• /proc/stat CPU metrics — Lightweight system-level CPU load measurement to correlate with UI blocks without requiring system permissions beyond READ_LOGS

• Synchronous block detection and logging during dispatchEnd callback
  • Why: Ensures no block events are missed and timing is accurate to main thread
  • Consequence: Brief serialized overhead on main thread after

Looper.setMessageLogging() conflict: if your app or another library already calls getMainLooper().setMessageLogging(), BlockCanary's hook will be overwritten—requires coordination (issue #27 referenced in README). Android 8+ notification channels: the library predates Android 8 NotificationChannel enforcement; may fail silently or crash on newer APIs without channel setup. Storage permissions: LogWriter writes to app cache/files but file paths are not documented—ensure READ/WRITE_EXTERNAL_STORAGE if needed. No-op module must match: release builds must use blockcanary-android-no-op to avoid bloat; mixing implementations causes unexpected overhead.

• Looper message logging hook — BlockCanary's entire detection mechanism relies on Looper.setMessageLogging() to intercept every Choreographer frame; understanding how this hook works is essential to troubleshoot conflicts or extend the monitoring.
• 16ms frame budget (60 FPS vsync interval) — Android targets 60 FPS on most devices, meaning each frame must complete in ≤16ms; BlockCanary uses this as the default jank threshold and the README configures it via int.xml.
• Stack sampling and CPU profiling — BlockCanary captures periodic stack traces (50ms intervals) and CPU usage during detected blocks to pinpoint root causes (I/O, loops, GC) rather than just reporting jank duration.
• Build flavor no-op pattern — The blockcanary-android-no-op module provides compile-time empty implementations for release builds, eliminating runtime overhead without conditional code in app—standard Android performance pattern.
• Main thread ANR detection without crashing — Unlike ANRs (which kill the app), BlockCanary detects ANR-level blocking (>5s worth of 16ms frame delays) gracefully and reports via notification, enabling in-production diagnostics.
• White-list and concern-package filtering — BlockCanary allows developers to ignore known third-party library jank and focus on app-owned code via white-list/concern-package configuration, reducing noise in diagnostics.

• square/leakcanary — Spiritual predecessor and UI/UX inspiration for BlockCanary; detects memory leaks rather than jank but uses similar notification-based reporting pattern
• facebook/Battery-Historian — Complementary Android performance profiling tool; captures power drain, CPU scheduling, and I/O waiting that often correlates with BlockCanary-detected jank
• google/android-perfettoui — System-level frame timing and Looper tracing via Perfetto; can be used alongside BlockCanary to validate detected blocks match systrace
• AndroidPerformanceMonitor/OkBuck — Buck build system integration for modular Android builds; some users combine BlockCanary monitoring with OkBuck's incremental compilation to reduce jank during development
• JakeWharton/butterknife — Companion library for annotation-driven UI binding; reduces main-thread work and pairs well with BlockCanary to quantify jank reduction from view-binding refactors

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 unit tests for BlockCanaryInternals.java and LooperMonitor.java

The core monitoring logic in blockcanary-analyzer lacks unit test coverage. BlockCanaryInternals.java manages the lifecycle of the monitoring system, and LooperMonitor.java handles the actual block detection via Looper instrumentation. These are critical components that would benefit from comprehensive unit tests to prevent regressions, especially around edge cases like rapid start/stop cycles, thread safety, and sampling behavior.

• [ ] Create blockcanary-analyzer/src/test/java/com/github/moduth/blockcanary/BlockCanaryInternalsTest.java
• [ ] Create blockcanary-analyzer/src/test/java/com/github/moduth/blockcanary/LooperMonitorTest.java
• [ ] Add test cases for monitor lifecycle (start, stop, restart)
• [ ] Add test cases for sampling accuracy in CpuSampler.java and StackSampler.java
• [ ] Add testImplementation dependency for JUnit and Mockito in blockcanary-analyzer/build.gradle

Add GitHub Actions CI workflow for automated testing and publishing

The repo has gradle-mvn-push.gradle for Maven Central publishing but no CI/CD pipeline visible. A GitHub Actions workflow would automate: running unit tests on PRs, checking ProGuard configuration validity, verifying builds across Android API levels, and automating Maven Central releases. This would catch integration issues early and ensure consistent publishing.

• [ ] Create .github/workflows/build-and-test.yml for PR validation (compile, unit tests, lint)
• [ ] Create .github/workflows/publish.yml for Maven Central releases triggered by tags
• [ ] Configure workflow to test against minSdkVersion (LIBRARY_MIN_SDK_VERSION) and targetSdkVersion
• [ ] Add gradle.properties secrets for Maven credentials in GitHub repository settings

Add integration tests demonstrating block detection scenarios in blockcanary-android

The blockcanary-android module has UI components (BlockCanaryUi.java, DisplayService.java) and analytics (Uploader.java) but no integration tests showing end-to-end block detection, notification display, or data flow. Adding instrumented tests would verify the complete monitoring pipeline works correctly and would serve as usage examples for contributors.

• [ ] Create blockcanary-android/src/androidTest/java/com/github/moduth/blockcanary/BlockDetectionIntegrationTest.java
• [ ] Add test scenario: simulate main thread block and verify DisplayService notification triggered
• [ ] Add test scenario: verify BlockInfo is correctly populated with stack traces and CPU data
• [ ] Add testImplementation dependencies (AndroidX Test, Espresso) to blockcanary-android/build.gradle

• Add unit tests for StackSampler.java and CpuSampler.java sampling accuracy across Android API levels 21–33; currently no test files visible in blockcanary-analyzer/.
• Document the white-list and concern-package feature (mentioned in CHANGELOG 1.3.0) with concrete examples in README or JavaDoc—currently missing from public docs.
• Add Android 8+ NotificationChannel support in the notification dispatch code (inferred but not in file list) and test on API 26+ emulator; file a PR against blockcanary-android.

The AndroidPerformanceMonitor (BlockCanary) codebase has moderate security concerns, primarily related to build configuration and code protection. The most critical issues are: (1) disabled code minification in releases, exposing internal monitoring logic to reverse engineering; (2) deprecated Gradle dependency configurations; and (3) broad JAR file inclusion without verification. The library's core function of monitoring UI performance and capturing stack traces necessitates careful handling of sensitive data to prevent information disclosure. Recommended improvements include enabling ProGuard minification, updating to modern Gradle configurations, and implementing strict logging sanitization.

• High · Outdated Gradle Dependency Configuration — blockcanary-analyzer/build.gradle, blockcanary-android/build.gradle. The build.gradle uses deprecated 'compile' configuration instead of 'implementation'. The 'compile' configuration was deprecated in Gradle 3.0 and removed in Gradle 7.0. This can cause build failures and prevents proper dependency management, potentially exposing transitive dependencies. Fix: Replace 'compile' with 'implementation' for proper dependency isolation and future Gradle compatibility.
• High · Missing ProGuard Configuration Enforcement — blockcanary-analyzer/build.gradle, blockcanary-android/build.gradle. ProGuard is disabled in release builds (minifyEnabled false) which means code obfuscation is not applied. This makes the app vulnerable to reverse engineering and exposes sensitive logic, including monitoring internals that could be exploited. Fix: Set minifyEnabled to true in release builds and maintain comprehensive ProGuard rules to obfuscate sensitive code paths.
• Medium · No Explicit Minification of Library — blockcanary-analyzer/build.gradle. The blockcanary-analyzer module, which handles performance monitoring and potentially sensitive sampling operations, is not minified. This exposes internal class names and method signatures that could be used for tampering or understanding security mechanisms. Fix: Enable code minification and ensure ProGuard rules properly obfuscate sensitive internal classes like LooperMonitor, StackSampler, and CpuSampler.
• Medium · Broad File Inclusion in Dependencies — blockcanary-analyzer/build.gradle, blockcanary-android/build.gradle. The build.gradle includes all JAR files from the 'libs' directory without explicit version control or verification (compile fileTree(dir: 'libs', include: ['*.jar'])). This could allow malicious JARs to be included without detection. Fix: Replace fileTree with explicit dependency declarations using Maven/Gradle coordinates with version pinning for better supply chain security.
• Medium · Potential Information Disclosure via Logging — blockcanary-analyzer/src/main/java/com/github/moduth/blockcanary/LogWriter.java. The LogWriter.java class is present which likely logs monitoring data. Without proper sanitization, this could expose sensitive stack traces, method names, and timing information to system logs that may be readable by other apps. Fix: Implement strict log sanitization, ensure sensitive data is hashed/redacted, and use appropriate Android log levels. Consider disabling debug logs in release builds.
• Medium · Unspecified SDK Versions — blockcanary-analyzer/build.gradle, blockcanary-android/build.gradle. The gradle.properties file references LIBRARY_COMPILE_SDK_VERSION and LIBRARY_TARGET_SDK_VERSION which are not visible in the provided content. If targeting outdated SDK versions, the app may miss critical security patches. Fix: Ensure compileSdkVersion and targetSdkVersion are set to the latest stable Android SDK version (currently API 34+) to receive security updates.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file is present in the repository, making it unclear how security issues should be reported or handled. Fix: Create a SECURITY.md file documenting responsible disclosure procedures for security vulnerabilities.

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.