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/sindresorhus/Gifski 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 1w ago
• 5 active contributors
• MIT licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sindresorhus/Gifski repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sindresorhus/Gifski.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sindresorhus/Gifski(\\.git)?\\b" \\
  && ok "origin remote is sindresorhus/Gifski" \\
  || miss "origin remote is not sindresorhus/Gifski (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 "Gifski/App.swift" \\
  && ok "Gifski/App.swift" \\
  || miss "missing critical file: Gifski/App.swift"
test -f "Gifski/GifskiWrapper.swift" \\
  && ok "Gifski/GifskiWrapper.swift" \\
  || miss "missing critical file: Gifski/GifskiWrapper.swift"
test -f "Gifski/AppState.swift" \\
  && ok "Gifski/AppState.swift" \\
  || miss "missing critical file: Gifski/AppState.swift"
test -f "gifski-api/src/lib.rs" \\
  && ok "gifski-api/src/lib.rs" \\
  || miss "missing critical file: gifski-api/src/lib.rs"
test -f "Gifski/Preview/PreviewRenderer.swift" \\
  && ok "Gifski/Preview/PreviewRenderer.swift" \\
  || miss "missing critical file: Gifski/Preview/PreviewRenderer.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 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/sindresorhus/Gifski"
  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).

Gifski is a native macOS app (written in Swift) that wraps the high-quality gifski Rust encoder to convert video files (MP4, MOV with H264/HEVC/ProRes) into optimized animated GIFs with thousands of colors per frame and up to 50 FPS. It uses pngquant's cross-frame palette algorithms and temporal dithering for quality, and gifsicle for lower-quality smaller files, while providing a GUI for frame cropping, speed adjustment, quality control, and looping. Single Xcode project structure: Gifski/App.swift is the entry point; EditScreen.swift, ConversionScreen.swift, CompletedScreen.swift form the UI flow; Crop/ directory isolates cropping logic (CropOverlayView.swift, CropSettings.swift); GIFGenerator.swift wraps the Rust encoder via GifskiWrapper.swift (bridged via Gifski-Bridging-Header.h); Components/ provides reusable UI elements (CheckerboardView.swift, IntTextField.swift, TrimmingAVPlayer.swift); AppState.swift holds the conversion state machine.

macOS users (designers, content creators, social media managers) who need to convert video clips to high-fidelity GIFs for sharing on Dribbble, Twitter, and other platforms; they want visual quality preservation without CLI usage. Also relevant for developers integrating the gifski encoder into Swift/macOS applications.

Production-ready and actively maintained. The app is published on the Mac App Store (requires macOS 26+), with older versions available for macOS 13+ back to 10.13. The underlying gifski Rust crate (v1.34.0) is well-established. However, repo commit recency from the file list is not explicit—check GitHub for latest activity, though the presence of modern build tooling (SwiftUI, Swift Package Manager integration) and recent version bumps suggest ongoing development.

Low risk for the Swift app layer (single active maintainer: Sindre Sorhus), but the Rust encoder dependency (gifski) is maintained by a separate party (ImageOptim). The app has minimal transitive dependencies due to Swift's stdlib-heavy approach; however, the macOS 26+ requirement is very aggressive and excludes most users (check if this is a typo, as macOS 26 doesn't exist yet—likely 14 or 15 intended). The lack of visible test files in the top 60 listing suggests limited test coverage.

Not visible from file listing alone—check GitHub releases and recent commit history. Based on file structure, active areas are likely: video trimming/cropping (Crop/ changes), frame-rate and quality sliders (EditScreen.swift refinements), estimated file size calculations (EstimatedFileSize.swift), and the share extension (Share Extension.xcscheme indicates continued investment in macOS integration features).

Clone: git clone https://github.com/sindresorhus/Gifski.git && cd Gifski. Open the Xcode project: open Gifski.xcodeproj. Install dependencies via Swift Package Manager (automatically resolved via Gifski.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved). Build and run: ⌘B in Xcode or xcodebuild -scheme Gifski -configuration Release.

Daily commands: In Xcode: select Gifski scheme (Gifski.xcscheme) → ⌘R to build and launch. For Release build: xcodebuild -scheme Gifski -configuration Release -derivedDataPath build. The app opens the main interface immediately; no CLI or server startup needed.

• Gifski/App.swift — Main SwiftUI application entry point that initializes the app state and orchestrates the primary screens and navigation flow.
• Gifski/GifskiWrapper.swift — Critical bridge to the gifski-api Rust library that handles all video-to-GIF conversion logic and must be understood for any encoding modifications.
• Gifski/AppState.swift — Central state management for the entire application holding conversion progress, settings, and UI state that affects all screens.
• gifski-api/src/lib.rs — Core Rust gifski library implementation; essential for understanding the underlying GIF encoding algorithm and quality parameters.
• Gifski/Preview/PreviewRenderer.swift — Renders real-time preview of GIF output during editing; critical path for frame processing and Metal-based composition.
• Gifski/GIFGenerator.swift — Orchestrates the end-to-end GIF generation pipeline, coordinating video input, frame extraction, and gifski-api calls.
• Gifski.xcodeproj/project.pbxproj — Xcode project configuration defining build targets, dependencies, and linking of the Rust gifski library to the Swift app.

Add a new conversion setting

1. Define the new property in AppState.swift as an @Published var with a sensible default (Gifski/AppState.swift)
2. Add a UI control in SettingsScreen.swift or EditScreen.swift to expose the setting to users (Gifski/SettingsScreen.swift)
3. Pass the setting value through GIFGenerator.swift to GifskiWrapper.swift (Gifski/GIFGenerator.swift)
4. Update the gifski-api Rust wrapper in GifskiWrapper.swift to map the setting to a gifski C API parameter (Gifski/GifskiWrapper.swift)

Add a new editing feature (crop, trim, resize)

1. Create a new data model struct in a new file under Gifski/Crop/ (e.g., CropSettings.swift pattern) to store the edit parameters (Gifski/Crop/CropSettings.swift)
2. Add a SwiftUI view in Gifski/Crop/ or Gifski/Components/ that implements gesture handling and visual feedback (Gifski/Crop/CropOverlayView.swift)
3. Integrate the view into EditScreen.swift below the video player (Gifski/EditScreen.swift)
4. Apply the transformation in ExportModifiedVideo.swift by modifying AVComposition or AVMutableVideoComposition (Gifski/ExportModifiedVideo.swift)

Modify the preview rendering algorithm

1. Update frame extraction logic in PreviewRenderer.swift to change frame selection or timing (Gifski/Preview/PreviewRenderer.swift)
2. Adjust Metal shader or composition settings in compositePreview.metal and PreviewVideoCompositor.swift (Gifski/Preview/compositePreview.metal)
3. Modify FullPreviewStream.swift if the async frame pipeline needs changes (Gifski/Preview/FullPreviewStream.swift)
4. Test the changes in EditScreen.swift where the preview is displayed in real-time (Gifski/EditScreen.swift)

Integrate a new quality/optimization option from gifski-api

1. Add the C API function binding to GifskiWrapper.swift by studying gifski.h (Gifski/GifskiWrapper.swift)
2. Expose the setting in AppState.swift with reasonable defaults (Gifski/AppState.swift)
3. Call the new function from GIFGenerator.swift during frame collection or before finalization (Gifski/GIFGenerator.swift)
4. Add UI toggle or slider in SettingsScreen.swift to allow user control (Gifski/SettingsScreen.swift)

• Swift + SwiftUI — Native macOS development with modern declarative UI, tight

• macOS 26+ requirement in README is likely a typo (macOS 26 doesn't exist); verify the actual deployment target in Config.xcconfig or Gifski.xcodeproj/project.pbxproj to avoid confusion.
• Rust FFI via gifski C API: Changes to the gifski Rust crate's C interface will break GifskiWrapper.swift—must keep Rust version and Swift wrapper in sync.
• SwiftLint rules in .swiftlint.yml may enforce style requirements; CI likely enforces them, so local builds may fail if linting is skipped.
• Share Extension target (Share Extension.xcscheme) is a separate build target; ensure you build and test both the main app and extension if modifying shared logic.
• Metal shaders present in the repo (Metal files in Crop/) are GPU-accelerated—metal shader compilation errors are opaque; may require Xcode logs to debug.
• AVPlayer + video trimming complexity: TrimmingAVPlayer.swift must handle variable playback rates, frame seeking, and memory management; modifications here can cause performance regressions or crashes during preview.
• No visible test suite in top 60 files suggests manual testing is primary validation; no CI configuration visible (check repo root for .github/workflows or .gitlab-ci.yml).

• Cross-frame color palette optimization (pngquant algorithm) — Gifski's core advantage—it builds a single optimized color palette across all video frames (unlike frame-by-frame GIF encoding), reducing color banding and file size while preserving visual quality across temporal transitions.
• Temporal dithering — Gifski applies dithering that varies across frames to hide color quantization artifacts in animation; essential to the 'high-quality' claim in smooth gradients and color transitions.
• SwiftUI state management with @StateObject and @ObservedObject — AppState.swift uses these property wrappers to bind video metadata and conversion progress across multiple screens (EditScreen, ConversionScreen, CompletedScreen); critical for reactive UI updates during long encoding operations.
• Objective-C FFI bridge (C API interop) — Gifski-Bridging-Header.h exposes Rust's C FFI to Swift; understanding how to safely marshal data across language boundaries is essential to modifying GifskiWrapper.swift or the Rust encoder interface.
• Metal graphics acceleration — The Crop/ directory likely uses Metal shaders for real-time GPU-accelerated preview scaling and rendering; performance of the preview depends on correct Metal pipeline setup.
• AVPlayer trimming and frame extraction — TrimmingAVPlayer.swift must accurately extract video frames at variable playback rates and handle seek precision; any bug here cascades into incorrect frame ranges in the final GIF.
• macOS Share Extension (App Extension target) — The Share Extension.xcscheme defines a separate binary target that integrates Gifski into the system Share menu; requires careful sandboxing, entitlements (Gifski.entitlements), and inter-process communication (IPC) to pass video URLs from other apps.

• ImageOptim/gifski — The upstream Rust encoder library that Gifski.swift wraps; critical dependency for all GIF encoding.
• sindresorhus/macos-app-template — A template repo by the same author showing best practices for modern macOS app development; likely influenced Gifski's architecture.
• losslesscut/losslesscut — Electron-based video trimming/cutting tool with cross-platform support; similar video-processing workflow and UI patterns.
• kornel/pngquant — Underlying color quantization algorithm powering gifski's high-quality palette generation; understanding pngquant is essential to Gifski's visual quality.
• sindresorhus/quick-look-plugins — Collection of macOS Quick Look plugins by the same author; Gifski could integrate or extend Quick Look previews for GIF files.

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 GIFGenerator.swift and GifskiWrapper.swift

The core GIF generation logic in GIFGenerator.swift and the Rust bridge in GifskiWrapper.swift lack visible unit tests. These are critical components that handle video-to-GIF conversion with various quality/compression settings. Adding tests would ensure stability across quality presets, frame rates, and dimension handling, which are all user-configurable via the UI.

• [ ] Create Tests/GIFGeneratorTests.swift with tests for estimated file size calculations and quality parameter validation
• [ ] Create Tests/GifskiWrapperTests.swift to test Rust FFI bindings and conversion progress callbacks
• [ ] Add test cases for edge cases: zero-duration videos, unsupported codecs, extreme quality/FPS values
• [ ] Integrate tests into Gifski.xcscheme to run on every build

Add GitHub Actions CI workflow for Swift linting and build validation

The repo contains .swiftlint.yml configuration but no visible CI workflow to enforce linting on PRs. Given the Xcode project structure with multiple targets (main app + Share Extension), automated validation on macOS would catch formatting issues and build failures before merge. This is especially important for a desktop app where binary compatibility matters.

• [ ] Create .github/workflows/swift-lint-and-build.yml with steps to: checkout, setup Xcode, run swiftlint with --strict mode, build both Gifski target and Share Extension target
• [ ] Configure workflow to run on pull_request and push to main branches
• [ ] Add swiftlint cache action to speed up repeated runs
• [ ] Document required Xcode version in README or workflow file (inferred from Config.xcconfig)

Extract CropSettings and aspect ratio logic into a dedicated SettingsViewModel

Crop functionality is scattered across Crop/CropSettings.swift, Crop/PickerAspectRatio.swift, and CropOverlayView.swift with state management potentially duplicated in EditScreen.swift. As new cropping features are added (e.g., preset aspect ratios, undo/redo), this will become harder to maintain. A dedicated ViewModel would centralize crop state, validation, and provide testable logic.

• [ ] Create Gifski/Crop/CropSettingsViewModel.swift to hold: current CropRect, aspect ratio locks, zoom level, and validation methods
• [ ] Refactor CropOverlayView.swift to receive CropSettingsViewModel as @StateObject instead of managing state directly
• [ ] Move aspect ratio preset logic from PickerAspectRatio.swift into ViewModel as a computed property or method
• [ ] Update EditScreen.swift to pass ViewModel down to all crop sub-views, removing duplicate @State properties
• [ ] Add unit tests for ViewModel in Tests/CropSettingsViewModelTests.swift to test aspect ratio locking, boundary validation, and rect clamping

• Add unit tests for EstimatedFileSize.swift: Currently no test file visible; create Gifski/EstimatedFileSizeTests.swift with test cases for various video dimensions, qualities, and frame rates to improve reliability of the file-size prediction UI.
• Document the Crop/CropSettings.swift data model: Add detailed comments explaining aspect-ratio constraints, handle-position calculations (CropHandlePosition.swift), and the mathematical relationship between CropRect coordinates and video frame dimensions for future maintainers.
• Extract quality presets into a localized constants file: Move hardcoded quality labels and frame-rate defaults from EditScreen.swift and Constants.swift into a structured data file (e.g., Gifski/QualityPresets.swift) to support easier UI testing and future localization.

The Gifski codebase demonstrates reasonable security practices for a macOS application, with a native Swift/Objective-C implementation and clear separation of concerns. However, there are notable concerns: (1) The AGPL-3.0 license of the gifski-api dependency presents significant legal and compliance risks for a proprietary app, requiring urgent legal review; (2) FFmpeg integration introduces potential vulnerability surface for untrusted video input; (3) Dependency management lacks formal security scanning and SBOM documentation; (4) No visible hardcoded secrets or injection vulnerabilities in the file structure, which is positive. The app appears to follow secure coding practices in terms of input handling and sandboxing, but license compliance and supply chain security should be prioritized.

• High · AGPL-3.0 License Compliance Risk — gifski-api/Cargo.toml (license field). The gifski-api dependency uses AGPL-3.0-or-later license. This is a strong copyleft license that requires source code disclosure for any modifications and networked use. Integrating AGPL code into a proprietary macOS app (Gifski) may create licensing conflicts and compliance obligations. Fix: Review legal implications of AGPL-3.0 integration. Consider: 1) Obtaining legal counsel on AGPL compliance, 2) Evaluating alternative GIF encoding libraries with permissive licenses (MIT, Apache 2.0), 3) If continuing with gifski, ensure proper source code availability mechanisms are in place.
• Medium · Outdated or Unspecified Rust Dependency Versions — gifski-api/Cargo.toml (dependencies section). Several dependencies use loose version constraints that may allow pulling in vulnerable minor/patch versions: clap (4.5.32), gif (0.13.1), imagequant (4.3.4), etc. Without pinned versions or lock file review, transitive dependencies could introduce known vulnerabilities. Fix: 1) Review Cargo.lock for any known CVEs in locked versions, 2) Implement dependency scanning using cargo-audit or similar tools, 3) Pin critical dependencies to exact versions where possible, 4) Establish a regular dependency update cadence with security testing.
• Medium · FFmpeg Optional Dependency without Security Boundary — gifski-api/Cargo.toml (ffmpeg-next dependency). FFmpeg is included as an optional dependency with features=['codec', 'format', 'filter', 'software-scaling']. FFmpeg has a history of security vulnerabilities. If enabled without proper sandboxing or input validation, it could process untrusted video files with potential for code execution. Fix: 1) Implement strict input validation on video files before passing to FFmpeg, 2) Consider sandboxing FFmpeg processing (e.g., separate process with resource limits), 3) Keep FFmpeg library updated regularly, 4) Document which FFmpeg codecs are actually required and disable unnecessary ones.
• Low · Missing SBOM or Dependency Documentation — Repository root / gifski-api. No Software Bill of Materials (SBOM) found in the repository. This makes it difficult for security audits and compliance tracking of all transitive dependencies and their licenses. Fix: 1) Generate and maintain SBOM using tools like cargo-sbom or cyclonedx, 2) Include SBOM in releases, 3) Document all direct and transitive dependencies with their versions and licenses.
• Low · Entitlements Configuration Review Needed — Gifski/Gifski.entitlements, Share Extension/Share_Extension.entitlements. The app uses entitlements files (Gifski.entitlements, Share_Extension.entitlements) but without visibility into their contents, potential over-privileging cannot be verified. The app requests file system access for video processing. Fix: 1) Review entitlements files to ensure principle of least privilege, 2) Request only necessary file system access (video input/output directories), 3) Avoid requesting network access unless required, 4) Use app sandboxing where possible.

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.