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/kean/Nuke 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 2d ago
• MIT 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 kean/Nuke repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kean/Nuke.

What it runs against: a local clone of kean/Nuke — 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 kean/Nuke | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/Nuke/ImageTask.swift" \\
  && ok "Sources/Nuke/ImageTask.swift" \\
  || miss "missing critical file: Sources/Nuke/ImageTask.swift"
test -f "Sources/Nuke/ImageRequest.swift" \\
  && ok "Sources/Nuke/ImageRequest.swift" \\
  || miss "missing critical file: Sources/Nuke/ImageRequest.swift"
test -f "Sources/Nuke/ImageResponse.swift" \\
  && ok "Sources/Nuke/ImageResponse.swift" \\
  || miss "missing critical file: Sources/Nuke/ImageResponse.swift"
test -f "Sources/Nuke/Caching/ImageCache.swift" \\
  && ok "Sources/Nuke/Caching/ImageCache.swift" \\
  || miss "missing critical file: Sources/Nuke/Caching/ImageCache.swift"
test -f "Sources/Nuke/Caching/DataCache.swift" \\
  && ok "Sources/Nuke/Caching/DataCache.swift" \\
  || miss "missing critical file: Sources/Nuke/Caching/DataCache.swift"

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

Nuke is a lean, high-performance image loading and caching framework for Swift that downloads, decodes, processes, and displays images across iOS, macOS, watchOS, tvOS, and visionOS. It provides a robust pipeline architecture with memory/disk caching, image processing, progressive JPEG support, and request coalescing—compiling in under 2 seconds with an automated test suite 2x the codebase size. Core monolithic structure: the main source code lives in a single Nuke module (Swift Package Manager) with companion modules NukeUI for SwiftUI/UIKit components and optional plugins. Documentation is centralized in Documentation/Nuke.docc/ using Apple's DocC format, organized by feature area (Essentials, Customization, Performance, Caching). CI/CD orchestration in .github/workflows/; build artifacts in .scripts/.

Swift app developers building iOS/macOS/watchOS/tvOS/visionOS applications who need a lightweight, customizable image loading system without the overhead of heavier frameworks; particularly those who value performance, compile speed, and advanced features like prefetching, resumable downloads, and HEIF/WebP/GIF support.

Production-ready and actively maintained since 2015. The presence of 13 migration guides (Nuke 4–13), extensive DoCC documentation, comprehensive CI/CD in .github/workflows/ci.yml, Shell-based validation scripts, and swiftlint configuration indicate a mature project. Commit recency and the detailed changelog suggest ongoing active development.

Low risk. Single author (kean) is a known, trusted maintainer in the Swift community. The test suite is 2x codebase size, indicating strong test coverage. No external binary dependencies listed—only Swift Package Manager. Major version releases are well-documented in Documentation/Migrations/ with clear upgrade paths, reducing breaking-change surprises.

The repository is actively maintained with visionOS support added (visible in platform badges), and recent migration guides through Nuke 13 suggest ongoing API refinement. The .scripts/ directory and GitHub Actions workflow indicate continuous integration and validation of new features. No specific PR backlog visible in the file list, but the comprehensive DoCC documentation suggests focus on developer experience.

Clone and validate:

git clone https://github.com/kean/Nuke.git
cd Nuke
bash .scripts/validate.sh

For Swift Package Manager integration in your own project: swift package add https://github.com/kean/Nuke.git. Run tests with bash .scripts/test.sh and linting with bash .scripts/lint.sh.

Daily commands: This is a framework library, not an app. For development:

bash .scripts/test.sh          # Run test suite
bash .scripts/lint.sh          # Run SwiftLint
bash .scripts/validate.sh      # Full validation
bash .scripts/create-xcframeworks.sh  # Build binary xcframeworks

Open Package.swift in Xcode for IDE development, or use swift build for CLI builds.

• Sources/Nuke/ImageTask.swift — Core abstraction for representing an ongoing image load operation; all image requests flow through this interface
• Sources/Nuke/ImageRequest.swift — Defines the immutable request object that configures what image to load, where to load it from, and how to process it
• Sources/Nuke/ImageResponse.swift — Encapsulates the result of a successful image load, including the image container and metadata
• Sources/Nuke/Caching/ImageCache.swift — In-memory image cache layer that intercepts requests before download; critical for performance
• Sources/Nuke/Caching/DataCache.swift — Disk cache for raw downloaded data; enables resumable downloads and reduces network traffic
• Sources/Nuke/Decoding/ImageDecoderRegistry.swift — Registry pattern for pluggable image decoders; determines how to decode different image formats (JPEG, HEIF, WebP, GIF)
• Sources/Nuke/ImageContainer.swift — Wrapper around decoded images with associated metadata; primary data structure flowing through the pipeline

Add support for a custom image format

1. Create a new decoder struct conforming to ImageDecoding protocol in Sources/Nuke/Decoding/ (Sources/Nuke/Decoding/ImageDecoding.swift)
2. Implement decode(data:urlResponse:) -> ImageContainer? to parse your format and return a decoded image (Sources/Nuke/Decoding/ImageDecoding.swift)
3. Register your decoder with the global ImageDecoderRegistry.shared.register() at app startup (Sources/Nuke/Decoding/ImageDecoderRegistry.swift)
4. The registry will check your decoder's isSupported(for:) method when processing responses; include your MIME type there (Sources/Nuke/Decoding/ImageDecoderRegistry.swift)

Implement a custom disk cache backend

1. Create a struct conforming to DataCaching protocol defining key/value storage operations (Sources/Nuke/Caching/DataCaching.swift)
2. Implement cachedData(for:) and storeData(_:for:) methods for your backend (e.g., SQLite, custom file layout) (Sources/Nuke/Caching/DataCaching.swift)
3. Pass your implementation to ImagePipelineConfiguration.dataCaching during pipeline initialization (Sources/Nuke/ImageRequest.swift)
4. The pipeline will automatically use your cache layer for resumable downloads and offline scenarios (Sources/Nuke/Caching/DataCache.swift)

Add a custom image processor to the pipeline

1. Define a struct conforming to ImageProcessing protocol (check ImageRequest for processor protocol) (Sources/Nuke/ImageRequest.swift)
2. Implement process(_:) -> UIImage? to transform the decoded image (resize, blur, tint, etc.) (Sources/Nuke/ImageRequest.swift)
3. Add your processor to ImageRequest via the processors parameter or create a pipeline policy in configuration (Sources/Nuke/ImageRequest.swift)
4. Processors are applied after decoding and before memory caching; results are cached by processor identity (Sources/Nuke/ImageContainer.swift)

• Swift with Async/Await support — Modern concurrency model avoids callback hell; works seamlessly with SwiftUI and structured concurrency
• ImageIO framework (native iOS/macOS API) — Hardware-accelerated image decoding with HEIF, JPEG2000, and progressive JPEG support; minimal dependencies
• Multi-tier caching (memory + disk) — Memory cache is fast (0–5ms hit); disk cache survives app restarts and enables offline scenarios; balances speed vs. storage
• Request coalescing & priority queue — Prevents duplicate downloads of the same image; prioritizes visible images (e.g., in scroll view) over background prefetch
• Protocol-based customization (ImageDecoding, ImageCaching, DataCaching) — Enables drop-in replacement of decoders, caches, and processors without forking; extensibility without API bloat

• Lean codebase (~2000 lines core) vs. batteries-included framework

  • Why: Target simplicity and fast compilation; assume integrators will extend via protocols rather than built-in options
  • Consequence: Some use cases require custom code; trade flexibility for minimal app size and startup time

• Memory cache only for fully decoded images (no raw data cache in RAM)

  • Why: Decoded images are the bottleneck for display; raw data would consume memory without user-visible benefit
  • Consequence: Re-decoding on memory pressure; disk cache is the fallback for cheap re-entry

• No built-in image format conversion (e.g., HEIF → JPEG on older iOS)

  • Why: Keeps framework lean; defer to native APIs and let integrators add via custom decoder/processor
  • Consequence: Integrators targeting old iOS versions must implement compatibility layer

• Request coalescing by URL only (not by content hash or request identity)

  • Why: Deterministic; avoids logic bugs from custom equality; simpler to reason about
  • Consequence: Two requests with different processors might not share a download (conservative but safe)

• Not a real-time streaming system; does not support live video or frame-by-frame updates
• Not a browser; does not parse HTML or resolve relative URLs
• Not a full image editor; minimal in-memory transformation APIs (use vImage or Core Image for complex processing)
• Not a database; caching is ephemeral and not queryable
• Does not handle authentication beyond standard HTTP headers (no OAuth integration)
• Does not support Android or Linux (iOS/macOS/watchOS/tvOS/visionOS only)

No required environment variables or external services detected in the file list. Key gotchas: (1) The framework supports multiple platforms (iOS, macOS, watchOS, tvOS, visionOS)—conditional compilation may hide platform-specific behavior; (2) Caching behavior is multi-layered (memory + disk)—changes to one tier can have unexpected effects on the other; (3) Request coalescing is transparent—duplicate simultaneous requests are deduplicated, which can surprise developers unfamiliar with the pipeline design; (4) Image processing is asynchronous—memory pressure during decoding can cause subtle timing issues in tests.

• Image Request Coalescing — Nuke deduplicates simultaneous requests for the same image URL, reducing redundant network calls and memory copies; understanding this prevents subtle bugs when loading the same image in multiple UI elements
• Multi-Layer Caching (Memory + Disk) — Nuke's cache architecture separates memory cache (fast, limited) from disk cache (persistent, unlimited); knowing these layers helps optimize memory pressure and startup performance
• Progressive JPEG Decoding — Nuke supports incremental rendering of progressive JPEGs; essential for understanding streaming image loads and why baseline JPEGs behave differently
• Image Decompression & Memory Decompression — Nuke decompresses images from disk cache into memory before rendering, reducing CPU spike at display time; critical for understanding frame drops in scroll views
• Async/Await with Progress Streaming — Nuke's imageTask(with:) returns a task that streams progress via for await loops while awaiting final image; understanding this pattern is core to modern Swift concurrency in Nuke
• Protocol-Based Customization (ImageDecoding, ImageProcessing) — Nuke's architecture relies on protocol extensions for decoders and processors, allowing runtime swapping without forking; knowing this pattern enables powerful customization without modifying core code
• HEIF & WebP Support — Modern formats reduce file size; Nuke's format detection and decoder routing handles these transparently, but understanding format negotiation helps optimize for different devices and OS versions

• SDWebImage/SDWebImage — Direct competitor in the Swift/Objective-C image loading space; more mature but heavier, useful for comparing design trade-offs and feature parity
• kingfisher-io/Kingfisher — Modern Swift-native alternative with similar goals (lightweight, SwiftUI-first); reference for comparing API design and async/await adoption
• kean/NukeUI — Official companion repository providing SwiftUI and UIKit integration layers (LazyImage component) built on top of Nuke core
• kean/NukeDemo — Official example application demonstrating real-world usage patterns, prefetching, progressive loading, and custom processing pipelines
• pointfreeco/swift-composable-architecture — Architectural inspiration for async/await patterns and state management that Nuke's request coalescing and progress tracking leverage

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 comprehensive tests for ImagePipeline configuration and delegate callbacks

The repo has extensive documentation for ImagePipeline, ImagePipelineConfiguration, and ImagePipelineDelegate (see Documentation/Nuke.docc/Extensions/), but the test suite likely lacks thorough coverage of configuration edge cases, delegate callback ordering, and pipeline lifecycle events. Given that the test suite is 2x the codebase size, this is a high-value area where specific scenarios (cache layer interactions, concurrent requests, delegate error handling) need verification.

• [ ] Examine existing tests in Nuke.xcodeproj for ImagePipeline test coverage
• [ ] Create test cases for ImagePipelineConfiguration combinations (cache settings, decoder options, etc.)
• [ ] Add tests for ImagePipelineDelegate callbacks in various scenarios (success, failure, cancellation, prefetching)
• [ ] Add tests for multi-layer cache interactions and delegate priority handling
• [ ] Run tests via .scripts/test.sh to validate

Add migration guide and deprecation tests for Nuke 13→14 transition

The repo maintains detailed migration guides through Nuke 13 (Documentation/Migrations/Nuke 13 Migration Guide.md), but there's likely a gap for the next major version. Create a structured PR that adds Nuke 14 migration guide, identifies deprecated APIs, and adds tests to ensure old APIs emit proper deprecation warnings while maintaining backward compatibility.

• [ ] Review CHANGELOG.md and recent commits to identify breaking changes for v14
• [ ] Create Documentation/Migrations/Nuke 14 Migration Guide.md following existing migration guide patterns
• [ ] Add deprecation warning tests for any public APIs that should be phased out
• [ ] Verify existing tests still pass with deprecation warnings via .scripts/test.sh
• [ ] Update Documentation/Nuke.docc/Nuke.md with version matrix if needed

Add platform-specific integration tests for visionOS, tvOS, and watchOS image rendering

The README shows support for iOS, macOS, watchOS, tvOS, and visionOS, but CI workflow (.github/workflows/ci.yml) and test scripts (.scripts/test.sh) likely only test iOS/macOS. Create platform-specific test targets that verify image loading, caching, and processing work correctly on watchOS (memory constraints), tvOS (display rendering), and visionOS (new platform) with appropriate assertions.

• [ ] Review .github/workflows/ci.yml to identify which platforms are currently tested
• [ ] Create separate test targets for watchOS, tvOS, and visionOS in Nuke.xcodeproj
• [ ] Add integration tests for memory-constrained scenarios (watchOS cache behavior)
• [ ] Add rendering tests for display correctness on tvOS and visionOS
• [ ] Update CI workflow to run platform-specific tests and document in .scripts/test.sh

• Add image format support documentation: Create a guide in Documentation/Nuke.docc/Customization/ImageFormats/ explaining how to implement a custom decoder for a new image format (e.g., AVIF or JPEGXL), with runnable code examples and performance considerations.: The supported-image-formats.md exists but lacks a step-by-step decoder implementation tutorial. This is a documentation-only contribution with no code risk.
• Enhance progressive JPEG documentation: Expand Documentation/Nuke.docc/Customization/ImageFormats/image-decoding.md with a detailed walkthrough of how progressive JPEG decoding works in Nuke, including memory trade-offs and configuration options.: Progressive JPEG is listed as a key feature in the README but no dedicated documentation exists. New contributors can research and document this without modifying core logic.
• Add prefetching best practices guide: Create Documentation/Nuke.docc/Performance/prefetching-best-practices.md with concrete examples of prefetching strategies (list view, carousel, grid), common pitfalls (over-prefetching), and memory management patterns.: Documentation/Nuke.docc/Performance/prefetching.md exists but is likely sparse. This fills a gap new developers hit immediately when implementing scroll-based prefetch logic.

The Nuke image loading framework demonstrates good security practices overall. As a specialized library for image handling, it has no apparent hardcoded credentials, SQL injection risks, or XSS vulnerabilities in the visible file structure. The codebase appears well-maintained with comprehensive test suites (2x codebase size) and structured documentation. However, minor improvements could include: (1) explicit HTTPS enforcement documentation for remote image loading, (2) a formal vulnerability disclosure policy (SECURITY.md), and (3) security documentation around the caching system's handling of potentially sensitive image data. No critical or high-severity vulnerabilities were identified from the available file structure and documentation.

• Low · Missing HTTPS enforcement documentation — Sources/Nuke (general architecture). The codebase is an image loading system that handles remote image fetching. While not visible in the file structure, image loading systems should enforce HTTPS for remote URLs to prevent man-in-the-middle attacks and ensure image integrity. Fix: Ensure the DataLoader and related network components enforce HTTPS for remote image URLs. Document this security requirement in the API documentation and consider adding warnings for HTTP URLs.
• Low · No visible security policy or vulnerability disclosure — Repository root. The repository lacks a SECURITY.md file or clear vulnerability disclosure policy. While the project has multiple migration guides and documentation, there's no clear process for reporting security issues responsibly. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process, security contact information, and supported versions receiving security updates.
• Low · Caching system security considerations not documented — Sources/Nuke/Caching/. The codebase includes DataCache and caching mechanisms (Sources/Nuke/Caching/). While caching is necessary for performance, the security implications of caching sensitive image data are not immediately apparent in the file structure. Fix: Document security considerations for cached image data, including: cache expiration policies, handling of sensitive/private images, cache location permissions, and guidelines for users to clear sensitive cached data when needed.

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.