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/getActivity/XXPermissions 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.

GO — Healthy across all four use cases

• Last commit 5w ago
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "getActivity/XXPermissions(\\.git)?\\b" \\
  && ok "origin remote is getActivity/XXPermissions" \\
  || miss "origin remote is not getActivity/XXPermissions (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 "library/src/main/java/com/hjq/permissions/XXPermissions.java" \\
  && ok "library/src/main/java/com/hjq/permissions/XXPermissions.java" \\
  || miss "missing critical file: library/src/main/java/com/hjq/permissions/XXPermissions.java"
test -f "library/src/main/java/com/hjq/permissions/core/PermissionRequestMainLogic.java" \\
  && ok "library/src/main/java/com/hjq/permissions/core/PermissionRequestMainLogic.java" \\
  || miss "missing critical file: library/src/main/java/com/hjq/permissions/core/PermissionRequestMainLogic.java"
test -f "library/src/main/java/com/hjq/permissions/core/PermissionChannelImpl.java" \\
  && ok "library/src/main/java/com/hjq/permissions/core/PermissionChannelImpl.java" \\
  || miss "missing critical file: library/src/main/java/com/hjq/permissions/core/PermissionChannelImpl.java"
test -f "library/src/main/java/com/hjq/permissions/fragment/factory/PermissionFragmentFactory.java" \\
  && ok "library/src/main/java/com/hjq/permissions/fragment/factory/PermissionFragmentFactory.java" \\
  || miss "missing critical file: library/src/main/java/com/hjq/permissions/fragment/factory/PermissionFragmentFactory.java"
test -f "library/src/main/java/com/hjq/permissions/OnPermissionCallback.java" \\
  && ok "library/src/main/java/com/hjq/permissions/OnPermissionCallback.java" \\
  || miss "missing critical file: library/src/main/java/com/hjq/permissions/OnPermissionCallback.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 63 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~33d)"
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/getActivity/XXPermissions"
  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).

XXPermissions is an Android permissions request framework that abstracts the complexity of handling runtime permissions across Android 6–16 (API 18+). It provides a unified API to request single/grouped permissions, special permissions (like SYSTEM_ALERT_WINDOW, MANAGE_STORAGE, health data), and handles version-specific permission models and platform quirks automatically. Single-module structure: library/ contains the core permission-handling engine, app/ is a feature-rich demo with PermissionConverter, PermissionDescription, and PermissionInterceptor classes for extensibility. Demo includes 20+ real-world permission request examples (accessibility, device admin, VPN, health data) and integration with DeviceCompat and Toaster frameworks.

Android app developers targeting multiple API levels who need to request permissions without boilerplate code or deep knowledge of Android's evolving permission model (normal, dangerous, special permissions, and Android 12+ restrictions).

Production-ready. The repo shows 758KB of Java code, a comprehensive demo app (MainActivity.java, multiple examples), detailed documentation in both English and Chinese, CI/CD via GitHub Actions (.github/workflows/android.yml), and is at version 28.2. However, actual GitHub stars/commits are not visible in the provided data; assess recency via the workflow file timestamps.

Low risk for active maintenance. Single maintainer (getActivity) may be a concern for critical production apps. The framework depends on com.github.getActivity:DeviceCompat (a sibling project by the same author), creating coupling. No visible breaking changes in the snippet, but Android 16 adaptation is ongoing (per README title). Monitor for API changes as Android evolves.

Active development to adapt the framework for Android 16 (as stated in the repo description). The demo app shows recent work on health data privacy policies (HealthDataPrivacyPolicyActivity.java) and advanced permission types (full-screen notifications, schedule exact alarms, health data). CI workflow (android.yml) is configured and should be running on commits.

Check README for instructions.

Daily commands: ./gradlew assembleDebug (or gradle assembleDebug if gradle wrapper missing) → deploy to emulator/device via adb install app/build/outputs/apk/debug/XXPermissions.apk or Android Studio's Run button. Demo runs on Android 5.0+ (minSdkVersion 18).

• library/src/main/java/com/hjq/permissions/XXPermissions.java — Main entry point API for the permission framework; all permission requests flow through this facade
• library/src/main/java/com/hjq/permissions/core/PermissionRequestMainLogic.java — Core permission request orchestration logic; handles delegation between RequestPermissions and StartActivity channels
• library/src/main/java/com/hjq/permissions/core/PermissionChannelImpl.java — Abstract base defining the permission channel contract; subclasses implement RequestPermissions vs StartActivity strategies
• library/src/main/java/com/hjq/permissions/fragment/factory/PermissionFragmentFactory.java — Factory for creating platform-specific permission fragments (Android vs AndroidX); critical for runtime behavior
• library/src/main/java/com/hjq/permissions/OnPermissionCallback.java — Primary callback interface returned to caller; defines granted/denied/exempted permission results
• library/src/main/java/com/hjq/permissions/DefaultPermissionInterceptor.java — Default interceptor for permission checks and customizable permission request descriptions
• app/src/main/java/com/hjq/permissions/demo/MainActivity.java — Demo application entry point showing all permission request patterns and use cases

Add Support for a New Special Permission Type

1. Define the new permission constant and metadata in a new permission type enum or class (library/src/main/java/com/hjq/permissions/core/PermissionChannelImplByStartActivity.java)
2. Update the permission routing logic to detect when this new permission is requested and route to appropriate channel (library/src/main/java/com/hjq/permissions/core/PermissionRequestMainLogic.java)
3. Add the Intent action and URI construction logic in the StartActivity channel implementation (library/src/main/java/com/hjq/permissions/core/PermissionChannelImplByStartActivity.java)
4. Add default description text for the new permission in DefaultPermissionDescription (library/src/main/java/com/hjq/permissions/DefaultPermissionDescription.java)

Customize Permission Request Behavior via Interceptor

1. Implement OnPermissionInterceptor interface in your application or copy DefaultPermissionInterceptor as a template (library/src/main/java/com/hjq/permissions/OnPermissionInterceptor.java)
2. Override requestPermissions() to intercept requests and perform custom checks (e.g., show custom dialogs before requesting) (app/src/main/java/com/hjq/permissions/demo/permission/PermissionInterceptor.java)
3. Register your interceptor via XXPermissions.setInterceptor() before calling request() (library/src/main/java/com/hjq/permissions/XXPermissions.java)

Provide Custom Permission Descriptions

1. Implement OnPermissionDescription interface to override permission description text and UI (library/src/main/java/com/hjq/permissions/OnPermissionDescription.java)
2. Create your custom description provider (reference DefaultPermissionDescription for all permission names) (app/src/main/java/com/hjq/permissions/demo/permission/PermissionDescription.java)
3. Register via XXPermissions.setPermissionDescription() before requesting permissions (library/src/main/java/com/hjq/permissions/XXPermissions.java)

Request Permissions with Callback Handling

1. Call XXPermissions.with(activity).permission(permissionList).request(callback) passing your OnPermissionCallback (library/src/main/java/com/hjq/permissions/XXPermissions.java)
2. Implement the callback interface handling onGranted(), onDenied(), and onExempted() methods (library/src/main/java/com/hjq/permissions/OnPermissionCallback.java)
3. The callback receives three lists: granted permissions, denied permissions, and exempted (special) permissions (app/src/main/java/com/hjq/permissions/demo/MainActivity.java)

• Fragment + RequestPermissions API — Fragments provide lifecycle awareness and support both startActivityForResult and requestPermissions, enabling unified permission handling across Android 6.0+ and special permission scenarios
• Interceptor + Description Provider patterns — Decouples framework logic from application-specific permission checks and UI text, allowing customization without modifying library code
• Channel abstraction (RequestPermissions vs StartActivity) — Encapsulates two different OS-level permission grant mechanisms (runtime permissions API vs Intent-based settings screens) behind a unified interface
• Factory pattern for Android/AndroidX fragments — Allows runtime detection and instantiation of correct Fragment base class without hard coupling to specific support library version

• Fragment-based implementation for all permission requests

  • Why: Fragments provide guaranteed lifecycle callbacks and simplify result handling across configuration changes
  • Consequence: Requires an Activity context and manages a retained fragment internally; slightly more overhead than direct API calls but more robust

• Static facade (XXPermissions) wrapping instance-based logic

  • Why: Provides simple, familiar API surface for developers while encapsulating complex state management internally
  • Consequence: Global state/interceptor configuration affects all permission requests; cannot easily have per-request interceptors

• Support both Android native and AndroidX Fragment libraries

  • Why: Maximize compatibility with both legacy and modern Android projects
  • Consequence: Adds complexity to fragment factory and requires runtime detection of available libraries

• Does not handle location/geolocation APIs directly—only manages OS permission grants
• Does

1. Signing keys (StoreFile, StorePassword, etc. in build.gradle) must be configured in gradle.properties or environment variables before release builds succeed; missing keys cause signing failures. 2. DeviceCompat 2.6 dependency must match the version declared in build.gradle—mismatches can cause runtime ClassNotFoundExceptions on older Android versions. 3. Android 16 adaptation is in progress; APIs may change—test against the latest release branch before shipping. 4. Permission groups vary by Android version; PermissionConverter must stay in sync with Android's official permission model, which changes with major OS releases. 5. Health data permissions (Android 14+) require special handling; ensure HealthDataPrivacyPolicyActivity.java is launched before requesting health permissions.

• Android Runtime Permissions Model (API 23+) — XXPermissions exists to hide the complexity of distinguishing normal (auto-granted), dangerous (runtime-requested), and special (intent-based) permissions; understanding this model is essential to using the framework correctly
• Permission Groups — Android groups related dangerous permissions (e.g., READ_CONTACTS + WRITE_CONTACTS); XXPermissions abstracts group-level requesting to reduce user friction. Knowing how groups map to individual permissions is critical for PermissionConverter.
• Special Permissions (Android 6+) — Permissions like SYSTEM_ALERT_WINDOW and MANAGE_STORAGE require Intent-based flows instead of runtime dialogs; XXPermissions handles these via PermissionDescription and PermissionInterceptor. Mishandling special permissions breaks core app features.
• Health Data Permissions (Android 14+) — Newest permission category requiring privacy policy disclosure and special handling; HealthDataPrivacyPolicyActivity.java in this repo shows implementation. Critical for fitness/medical apps.
• Version-Aware Compatibility Abstraction (via DeviceCompat) — XXPermissions uses DeviceCompat to query OS version and conditionally apply permission logic; understanding this pattern helps you extend the framework for future Android versions beyond 16
• Intent-Based Permission Requests — Some permissions (VPN, accessibility, device admin) are granted via system Settings intents, not runtime dialogs. PermissionInterceptor intercepts these to route users to the correct Intent flow.
• Callback-Based Asynchronous Result Handling — XXPermissions uses callback patterns (seen in PermissionInterceptor) to handle async permission results; understanding callback chains prevents race conditions when requesting multiple permission groups sequentially

• getActivity/DeviceCompat — Sibling framework used by XXPermissions to abstract OS version detection and device-specific behavior; essential for Android 16 compatibility logic
• permissions-dispatcher/PermissionsDispatcher — Annotation-based alternative for Android runtime permissions with similar goals but different API; useful for comparison
• EasyPermissions/EasyPermissions — Another popular Android permission wrapper framework; provides Rationale callbacks and simpler callback style
• getActivity/Toaster — Toast notification framework used by XXPermissions demo for user feedback; decouples toast logic from permission requests
• getActivity/TitleBar — Title bar UI component used throughout the XXPermissions demo app for consistent headers and navigation

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 Android 16 (API 36) permission compatibility tests in androidTest

The repo claims to 'Adapt to Android 16' but there's no visible androidTest directory with instrumented tests validating Android 16 permission behaviors. Android 16 introduces new permission restrictions (e.g., FOREGROUND_SERVICE_* permissions, foreground service type declarations). A test suite would ensure the framework correctly handles these new permission models and doesn't regress on older APIs.

• [ ] Create app/src/androidTest/java/com/hjq/permissions/demo/Android16PermissionTest.java
• [ ] Add test cases for Android 16+ specific permissions (FOREGROUND_SERVICE_HEALTH, FOREGROUND_SERVICE_MEDIA_PLAYBACK, etc.)
• [ ] Validate backward compatibility with Android 18-15 (minSdkVersion 18)
• [ ] Integrate androidTest into .github/workflows/android.yml CI pipeline
• [ ] Document test execution instructions in HelpDoc-en.md and HelpDoc-zh.md

Add GitHub Action workflow for automated permission compliance validation

The .github/workflows/android.yml exists but likely only builds the APK. Add a linting/validation workflow that scans app/src/main/AndroidManifest.xml against Android 16 permission requirements, detects missing <uses-permission> declarations, and validates that dangerous permissions are properly declared. This prevents silent permission-related regressions.

• [ ] Create .github/workflows/permission-lint.yml workflow file
• [ ] Add step to validate AndroidManifest.xml uses modern permission tags (android:maxSdkVersion for deprecated perms)
• [ ] Integrate lint-gradle or custom validation script for permission group definitions
• [ ] Add badge to README.md and README-en.md showing lint status
• [ ] Run workflow on pull requests and pushes to main branch

Create library/src/main/java/com/hjq/permissions/PermissionChangeLog.java documenting API/behavior changes per Android version

The library structure shows library/ module exists but there's no visible changelog for permission behavior changes across Android versions. Users extending or maintaining the framework need to understand what changed in Android 16 vs 15 vs 14. A dedicated class documenting version-specific behaviors, deprecated permission patterns, and migration guides would significantly reduce support issues.

• [ ] Create library/src/main/java/com/hjq/permissions/PermissionChangeLog.java as a public reference class
• [ ] Document Android 16 changes (new foreground service types, sensors permission consolidation, etc.)
• [ ] Document Android 12-15 changes (NEARBY_WIFI_DEVICES, PHOTO_PICKER_MEDIA, READ_MEDIA_* split, etc.)
• [ ] Add @deprecated annotations with migration hints for obsolete permission patterns
• [ ] Link from HelpDoc-en.md, HelpDoc-zh.md, Details-en.md, and Details-zh.md to this changelog

• Add unit tests for PermissionConverter.java to verify permission-to-manifest-string mapping across Android 6–16 (currently no test files visible in app/); this ensures compatibility when new permissions are added.
• Document the PermissionInterceptor extension API with a worked example in HelpDoc-en.md and HelpDoc-zh.md showing how to inject custom permission dialogs instead of system defaults.
• Create a migration guide (in Details-en.md / Details-zh.md) for apps upgrading from Support library (XXPermissions 26.8) to AndroidX (28.2+), with specific examples of what changed in the PermissionDescription and callback signatures.

• High · Keystore Credentials Potentially Exposed — app/AppSignature.jks, app/build.gradle (signingConfigs section). The file 'app/AppSignature.jks' is a keystore file containing sensitive signing credentials. If this file is committed to the repository with passwords stored in gradle.properties or build.gradle, it poses a significant security risk. The signingConfigs block references StorePassword, KeyAlias, and KeyPassword which may be hardcoded or exposed. Fix: 1. Remove the keystore file from version control immediately. 2. Store signing credentials in a secure location (e.g., GitHub Secrets, local machine, CI/CD secure variables). 3. Use environment variables or a local gradle.properties file (in .gitignore) for sensitive values. 4. Consider using Android App Signing by Google Play.
• High · Outdated androidx.appcompat Dependency — app/build.gradle (dependencies section). The dependency 'androidx.appcompat:appcompat:1.0.0' is significantly outdated (released in 2018). This version likely contains multiple known security vulnerabilities and lack of security patches for Android vulnerabilities. Fix: Update androidx.appcompat to the latest stable version (currently 1.6.x or higher). This ensures security patches and bug fixes are applied.
• Medium · Overly Permissive minSdkVersion — app/build.gradle (defaultConfig.minSdkVersion). The application targets minSdkVersion 18 (Android 4.3, released 2013). Supporting such old API levels means the app cannot enforce modern security features and exposes users on very old devices to unpatched vulnerabilities. Fix: Consider increasing minSdkVersion to at least 24 (Android 7.0, 2016) or higher (26+) to enforce modern security standards like TLS 1.2 and remove support for deprecated APIs.
• Medium · Unverified Third-Party Dependencies — app/build.gradle (dependencies: DeviceCompat, Toaster, TitleBar). Multiple external dependencies are included from GitHub (DeviceCompat, Toaster, TitleBar) and JitPack without explicit version pinning or verification. This increases supply chain attack risk if any dependency is compromised. Fix: 1. Pin specific versions instead of using dynamic version resolution. 2. Regularly audit and update dependencies. 3. Verify dependency sources and checksums. 4. Consider using dependency verification features in Gradle.
• Medium · Debug Build Signing Configuration — app/build.gradle (buildTypes.debug section). The debug build type uses the same signing configuration as release (signingConfigs.config). This is unusual and could lead to debug builds being signed with production credentials. Fix: Use Android's default debug keystore for debug builds. Only apply custom signing to release builds. Remove 'signingConfig signingConfigs.config' from the debug buildType.
• Low · LeakCanary Dependency in Debug Only — app/build.gradle (debugImplementation LeakCanary). While LeakCanary is correctly scoped to debugImplementation, ensure it's not accidentally included in release builds. This is generally a good practice but should be verified during build process. Fix: Maintain current configuration with debugImplementation scope. Verify through build variant configuration that it's excluded from release builds.
• Low · Missing Security-Related Proguard Rules — app/proguard-rules.pro, library/proguard-permissions.pro. The proguard-rules.pro file exists but the provided content doesn't show explicit rules for protecting sensitive code or APIs. Insufficient obfuscation could make reverse engineering easier. Fix: Review and enhance Proguard rules to: 1. Obfuscate sensitive classes and methods. 2. Keep permission-related APIs intact. 3. Add rules for any custom cryptographic operations. 4. Verify rules in release builds.
• Low · Potential Information Disclosure via GitHub Actions — .github/workflows/android.yml. The .github/workflows/android.yml file exists but content is not shown. CI/CD pipelines can inadvertently expose secrets or build credentials if misconfigured. Fix: 1.

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.