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/hdodenhof/CircleImageView 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

• 11 active contributors
• Apache-2.0 licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 89% 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 hdodenhof/CircleImageView repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hdodenhof/CircleImageView.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hdodenhof/CircleImageView(\\.git)?\\b" \\
  && ok "origin remote is hdodenhof/CircleImageView" \\
  || miss "origin remote is not hdodenhof/CircleImageView (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 "circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java" \\
  && ok "circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java" \\
  || miss "missing critical file: circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java"
test -f "circleimageview/src/main/res/values/attrs.xml" \\
  && ok "circleimageview/src/main/res/values/attrs.xml" \\
  || miss "missing critical file: circleimageview/src/main/res/values/attrs.xml"
test -f "circleimageview/build.gradle" \\
  && ok "circleimageview/build.gradle" \\
  || miss "missing critical file: circleimageview/build.gradle"
test -f "sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java" \\
  && ok "sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java" \\
  || miss "missing critical file: sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java"
test -f "sample/src/main/res/layout/activity_main.xml" \\
  && ok "sample/src/main/res/layout/activity_main.xml" \\
  || miss "missing critical file: sample/src/main/res/layout/activity_main.xml"

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

CircleImageView is a lightweight Android custom ImageView that renders images in a perfect circle, optimized for profile pictures. It uses BitmapShader for efficient rendering without creating bitmap copies, clipping paths, or double-drawing to canvas—making it faster and smoother than alternatives. Key features include customizable border width/color via XML attributes (civ_border_width, civ_border_color) and forced CENTER_CROP scaling. Simple library structure: single Gradle module under circleimageview/ containing one core file (circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java), one attrs definition (circleimageview/src/main/res/values/attrs.xml for border customization), and a sample app (sample/) demonstrating usage with MainActivity.java and test images.

Android app developers building social, messaging, or profile-heavy applications who need circular profile image views. Specifically developers using image loading libraries like Picasso or Glide and want a performant, drop-in replacement for standard ImageView that handles the circular clipping automatically.

This is a mature, production-ready library. The single-file implementation (CircleImageView.java) is stable and widely adopted (historically 7k+ stars on GitHub based on repository prominence). No active development is visible from the file structure, indicating it's feature-complete and maintenance-focused rather than actively evolving.

Low risk: zero external dependencies (only Android SDK), no breaking changes expected given the frozen feature set. Primary risk is single maintainer (hdodenhof) with no visible CI/CD pipeline in provided files and no test directory present, meaning regression detection relies on community reporting. The hard restriction on ScaleType (CENTER_CROP enforced, no alternatives) could be limiting for non-profile use cases.

Based on the file structure provided, no active development is indicated—this is a stable, maintenance-mode library. No changelog entries, PR branches, or feature branches are visible. The README documents known limitations (no adjustViewBounds support, no VectorDrawable efficiency, fade animation workarounds needed) suggesting the scope is intentionally frozen.

Clone and explore: git clone https://github.com/hdodenhof/CircleImageView.git && cd CircleImageView && ./gradlew build. To run the sample: ./gradlew sample:installDebug && adb shell am start -n de.hdodenhof.circleimageview.sample/.MainActivity. Gradle wrapper is provided (gradlew), no additional installation needed.

Daily commands: Development build: ./gradlew circleimageview:assemble. Sample app: ./gradlew sample:assembleDebug && adb install -r sample/build/outputs/apk/debug/sample-debug.apk. Full build validation: ./gradlew build. No emulator or live server required—this is a compiled library and APK deliverable.

• circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java — Core implementation of the circular ImageView using BitmapShader; this is the entire public API of the library.
• circleimageview/src/main/res/values/attrs.xml — Defines custom XML attributes (border radius, border color, border width) that users set on CircleImageView in layouts.
• circleimageview/build.gradle — Library build configuration specifying Android SDK versions, dependencies, and artifact publication settings.
• sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java — Sample application demonstrating how to use CircleImageView; shows the primary usage pattern for new integrators.
• sample/src/main/res/layout/activity_main.xml — XML layout showing CircleImageView declaration with custom attributes; reference for users implementing the library.
• README.md — Documents the library's design philosophy (BitmapShader vs clipPath/Xfermode), performance claims, and integration instructions.

• CircleImageView (Android Canvas, BitmapShader, Paint, custom TypedArray attribute parsing) — Custom ImageView subclass that measures itself as a square, reads custom XML attributes (border width/color), and renders the bitmap as a circle with optional border using BitmapShader.
  • Failure mode: If bitmap is null or invalid, onDraw() may throw NullPointerException or silently skip rendering; border color/width set to invalid values may cause rendering artifacts.
• Sample MainActivity (Android Activity, ImageView inflation, drawable resources) — Demonstrates creating and configuring CircleImageView instances programmatically; loads sample drawable asset.
  • Failure mode: If sample image asset (hugh.png) is missing, app crashes on resource lookup; improper CircleImageView configuration shows misaligned or invisible circles.
• Gradle Build System (Gradle 6.x+, Android Gradle Plugin 3.6.1) — Compiles library and sample modules, manages dependency resolution, packages AAR artifact for publication.
  • Failure mode: Version mismatches or missing jcenter/google repositories cause build failure; incorrect minSdk/targetSdk break runtime compatibility.

• XML Layout (activity_main.xml) → CircleImageView constructor — LayoutInflater parses custom attributes (civ_border_width, civ_border_color) and passes via AttributeSet to constructor.
• CircleImageView.setImageBitmap() or setImageDrawable() → Internal Drawable reference — Caller provides bitmap/drawable; CircleImageView stores reference for use in onDraw() shader setup.
• onDraw() method → BitmapSh — undefined

Add a new custom attribute to CircleImageView

1. Define the attribute in circleimageview/src/main/res/values/attrs.xml under the CircleImageView declare-styleable block (circleimageview/src/main/res/values/attrs.xml)
2. In CircleImageView.java, read the attribute in the init() or constructor method using typedArray.getXXX() (circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java)
3. Add a public setter method in CircleImageView.java to allow runtime updates; call invalidate() if the setter affects rendering (circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java)
4. Update sample/src/main/res/layout/activity_main.xml or sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java to demonstrate the new attribute (sample/src/main/res/layout/activity_main.xml)

Modify the drawing/rendering behavior of CircleImageView

1. Locate the onDraw() method and related drawing helper methods (setupShader, drawCircle logic) in CircleImageView.java (circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java)
2. Update the BitmapShader configuration, Paint settings, or canvas.drawCircle() calls to change appearance (circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java)
3. Test in the sample app by rebuilding sample/build.gradle and running on an emulator or device (sample/build.gradle)

Release a new version of the library

1. Update VERSION_NAME in gradle.properties to the new semantic version (gradle.properties)
2. Update the README.md with new features, usage examples, and the updated Gradle dependency coordinates (README.md)
3. Run ./gradlew build or ./gradlew :circleimageview:build to compile and package the library AAR (circleimageview/build.gradle)
4. Push tags and artifacts to the configured Maven repository (typically JCenter or Maven Central) (circleimageview/gradle.properties)

• BitmapShader — Efficiently tiles/stretches bitmap content into circle shape without copying bitmap or using expensive clipping operations; GPU-accelerated on modern Android.
• Custom ImageView (not Drawable) — Allows integration with any drawable type (Picasso, Glide, standard drawables) and simplifies attribute binding via XML layouts.
• Android Canvas/Paint API — Direct access to low-level drawing primitives (drawCircle) for full control; no abstraction overhead vs framework-provided RoundedImageView.
• Gradle multi-module (library + sample) — Separates publishable library code from demonstration; sample module depends on local library for quick iteration and testing.

• Single monolithic CircleImageView.java class

  • Why: Simplicity and ease of understanding; minimal surface area for bugs.
  • Consequence: Class handles measurement, attribute parsing, drawing, and shader setup; harder to extend or test individual concerns.

• No external runtime dependencies

  • Why: Reduces library size, simplifies dependency resolution, and avoids version conflicts in consumer apps.
  • Consequence: Cannot reuse pre-built utilities; all logic must be custom-written (e.g., attribute parsing, bitmap handling).

• BitmapShader + clipPath avoided

  • Why: BitmapShader is hardware-accelerated and anti-aliased; clipPath is neither on older Android versions.
  • Consequence: Better performance and visual quality but requires understanding of shader-based rendering for modifications.

• Does not handle image loading; consumers must use Picasso, Glide, or similar to fetch and pass Drawable/Bitmap.
• Does not provide animation framework; consumers must use ObjectAnimator or Transition API separately.
• Does not support non-circular shapes (ovals, rounded rectangles); scope is strictly circular images.
• Does not include accessibility features (content descriptions); consumers must add android:contentDescription in XML.
• Not a real-time video streaming widget; designed for static images only.

1. ScaleType is hardcoded to CENTER_CROP—attempting ImageView.setScaleType() to anything else throws an exception by design; no runtime config path exists. 2) Image loaders (Picasso, Glide) must disable fade animations (use noFade() or dontAnimate()) or images render corrupted; this is not in the source but critical for real-world use. 3) TransitionDrawable composites do not work and produce visual corruption. 4) adjustViewBounds XML attribute silently fails; the library does not support dynamic size adjustment. 5) No minSdkVersion constraint visible in provided files—check circleimageview/build.gradle for actual API level support (likely API 16+ based on typical Android library practices).

• BitmapShader — CircleImageView's core rendering technique—BitmapShader tiles bitmap content without creating copies or double-drawing, making it the key to its performance advantage. Understanding how it maps 2D texture coordinates to canvas is essential to modifying rendering behavior.
• Canvas clipping vs. Shader masking — CircleImageView deliberately avoids clipPath (slow, not hardware-accelerated, rough aliasing) and Xfermode (requires double-draw); instead uses Shader masking for efficiency. This architectural choice is why the library exists and understanding the tradeoff is essential.
• CENTER_CROP ScaleType enforced by design — CircleImageView throws an exception if ScaleType is changed from CENTER_CROP; this is a deliberate constraint limiting flexibility but ensuring predictable circle geometry for profile images. Modifying this would require reworking the bounds calculation logic.
• Paint and Shader composition — CircleImageView uses Paint objects with attached BitmapShader and Path stroking for borders; understanding Paint properties (setShader, setStrokeWidth, setColor) is required to extend border styling or add new visual features.
• TypedArray custom attribute inflation — XML attributes defined in attrs.xml (civ_border_width, civ_border_color) are inflated in CircleImageView constructor via TypedArray; modifying or adding new configurable properties requires both attrs.xml changes and TypedArray parsing code.
• Hardware acceleration in Android Canvas rendering — CircleImageView's design explicitly avoids clipPath and certain Xfermode operations because they are not hardware-accelerated; understanding which canvas operations are GPU-accelerated vs. software-rendered is critical to performance optimization decisions.

• vinc3m1/RoundedImageView — Direct predecessor acknowledged in README; provides rounded corners (non-circular) using similar BitmapShader technique, useful for comparison and understanding the BitmapShader pattern origins
• square/picasso — Primary image loading library CircleImageView is designed to work with; developers must call noFade() when loading into CircleImageView to avoid corruption artifacts
• bumptech/glide — Alternative image loading library that also integrates with CircleImageView; requires dontAnimate() configuration to prevent rendering corruption
• material-components/material-components-android — Modern Material Design library providing ShapeableImageView (API 21+) as a more flexible circular/rounded alternative; useful for developers building Material-compliant apps who may want to migrate away from CircleImageView

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 Android tests for CircleImageView rendering and edge cases

The repo lacks any visible test directory. CircleImageView is a custom rendering component that uses BitmapShader - this is critical to test across different Android API levels, bitmap sizes, and scaling modes. Current code has no test coverage for the bitmap shader logic, border drawing, or fill color application. Adding androidTest/ with Espresso tests would catch regressions in rendering behavior.

• [ ] Create circleimageview/src/androidTest/java/de/hdodenhof/circleimageview/ directory structure
• [ ] Add CircleImageViewTest.java with tests for: bitmap shader initialization, circular clipping, border rendering at various widths, fill color application, and bitmap scaling modes (CENTER_CROP, FIT_CENTER, etc.)
• [ ] Test edge cases: null bitmaps, very large bitmaps, different image formats (PNG, JPEG with transparency)
• [ ] Update circleimageview/build.gradle to include androidTest dependencies (androidx.test:rules, androidx.test.espresso:espresso-core)
• [ ] Verify tests run on multiple API levels using emulator or CI

Add GitHub Actions CI workflow to validate builds and tests across API levels

The repo has no .github/workflows/ directory visible. Without CI, contributors cannot verify their changes don't break compilation or functionality. A workflow should build both the library and sample app, run instrumented tests on emulator, and verify ProGuard rules (sample/proguard-rules.txt exists but isn't tested). This prevents regressions on pull requests.

• [ ] Create .github/workflows/android-ci.yml with matrix build for API levels 21, 28, 29, 30+
• [ ] Add gradle build steps: ./gradlew build (library), ./gradlew assembleDebug (sample app)
• [ ] Add instrumented test step: run tests on emulator using reactivecircus/android-emulator-runner action
• [ ] Add ProGuard validation: verify proguard-rules.txt is syntactically correct via lint or custom script
• [ ] Configure workflow to trigger on push to main and pull requests

Add Kotlin coroutine support and modern drawable loading example to sample app

The sample app (sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java) appears to be basic Java code with no examples of modern image loading patterns. CircleImageView claims Picasso compatibility but provides no example. Add a modern implementation using Coil or Glide with Kotlin to demonstrate best practices for 2024, matching what new contributors expect. This also documents attrs.xml features by showing them in use.

• [ ] Convert sample/src/main/java/de/hdodenhof/circleimageview/sample/MainActivity.java to Kotlin
• [ ] Add Glide or Coil dependency to sample/build.gradle
• [ ] Update sample/src/main/res/layout/activity_main.xml to include multiple CircleImageView instances showcasing: border_width, border_color, and fill_color attributes (defined in circleimageview/src/main/res/values/attrs.xml)
• [ ] Implement image loading with Glide/Coil placeholders and error handling
• [ ] Add code comments explaining how CircleImageView integrates with modern image libraries and why it doesn't need custom drawable implementations

• Add unit tests for CircleImageView: create circleimageview/src/test/java/de/hdodenhof/circleimageview/CircleImageViewTest.java with tests for border width/color application, forced CENTER_CROP scaling, and canvas rendering paths. Currently zero test coverage exists.
• Document the image loader integration workarounds in circleimageview/src/main/res/values/attrs.xml or via Javadoc: add @Deprecated warnings and links to Picasso/Glide fade-animation-disable patterns since the README mentions these limitations but the code doesn't guide developers.
• Add a configuration example to sample/src/main/res/layout/activity_main.xml showing gap-between-image-and-border workaround (using nested FrameLayout with padding) since the FAQ references issue #133 but no visual example exists in the sample app.

The CircleImageView library has a moderate security posture. The primary concerns are outdated build tools (Gradle 3.6.1 from 2020) and use of deprecated repositories (jcenter). These issues should be addressed immediately as they prevent access to security patches for the build system and its dependencies. The library itself appears to be a well-designed, focused component with minimal external dependencies, reducing attack surface. No hardcoded secrets, injection vulnerabilities, or infrastructure misconfigurations were detected. Updating build tooling and repository configuration will significantly improve security compliance.

• High · Outdated Gradle Build Tool — build.gradle (buildscript dependencies). The codebase uses com.android.tools.build:gradle:3.6.1, which was released in March 2020 and is significantly outdated. This version contains known security vulnerabilities and lacks modern security features and bug fixes available in current versions (7.x and 8.x). Fix: Update to the latest stable Gradle plugin version. Use com.android.tools.build:gradle:8.1.0 or later. Review Android Gradle Plugin release notes for breaking changes.
• Medium · Deprecated Repository Configuration — build.gradle (repositories section). The build configuration uses 'jcenter()' repository which was sunset by JFrog on May 1, 2021. While Google's Maven repository is present, relying on deprecated repositories can cause build failures and security issues. Fix: Remove jcenter() from all build.gradle files and rely solely on mavenCentral() and google() repositories. Verify all dependencies are available in these repositories.
• Medium · Missing Gradle Wrapper Version — gradle/wrapper/gradle-wrapper.properties. While gradle/wrapper/gradle-wrapper.jar is present, the gradle/wrapper/gradle-wrapper.properties file content was not provided. The Gradle wrapper version should be verified to ensure it's current and not vulnerable. Fix: Verify wrapper is using Gradle 8.0 or later. Check gradle-wrapper.properties for 'distributionUrl' and update if necessary. Ensure gradle-wrapper.jar is legitimate by validating checksums.
• Low · No Input Validation Visible in Custom View — circleimageview/src/main/java/de/hdodenhof/circleimageview/CircleImageView.java. CircleImageView is a custom ImageView that processes bitmap data. Without reviewing CircleImageView.java, potential risks include improper handling of malformed bitmap data or unchecked dimensions that could cause crashes or memory issues. Fix: Review CircleImageView.java for: (1) Proper null checks on bitmap data, (2) Bounds checking on canvas/bitmap dimensions, (3) Resource cleanup in onDraw() and destructor methods, (4) Safe handling of custom XML attributes in attrs.xml.
• Low · Missing ProGuard Configuration for Library — circleimageview/. The library module (circleimageview) does not have a consumer ProGuard rules file (consumer-rules.pro). While this is less critical for a simple view library, it's a best practice for Android libraries. Fix: Create circleimageview/consumer-rules.pro with appropriate rules (even if empty with comments explaining the library's requirements). Specify 'consumerProguardFiles' in circleimageview/build.gradle.

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.