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/ImageOptim/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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1w ago
• 13 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ Non-standard license (Other) — review terms

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

What it runs against: a local clone of ImageOptim/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 ImageOptim/gifski | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 39 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/encoderust.rs" \\
  && ok "src/encoderust.rs" \\
  || miss "missing critical file: src/encoderust.rs"
test -f "src/collector.rs" \\
  && ok "src/collector.rs" \\
  || miss "missing critical file: src/collector.rs"
test -f "src/c_api.rs" \\
  && ok "src/c_api.rs" \\
  || miss "missing critical file: src/c_api.rs"
test -f "src/bin/gifski.rs" \\
  && ok "src/bin/gifski.rs" \\
  || miss "missing critical file: src/bin/gifski.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
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/ImageOptim/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 high-quality GIF encoder written in Rust that wraps libimagequant (from pngquant) to produce animated GIFs with thousands of colors per frame using cross-frame palettes and temporal dithering. It accepts video via ffmpeg piping, Y4M files, or PNG frame sequences and outputs optimized GIF animations with significantly better quality than standard GIF encoders. Hybrid Rust/C architecture: src/lib.rs is the core library exposing both Rust and C APIs. src/bin/ contains multiple CLI entry points (gifski.rs main binary, ffmpeg_source.rs, png.rs, y4m_source.rs for different input formats). src/c_api.rs wraps the library for C consumers via gifski.h. src/wasm.rs provides WebAssembly bindings. Parallelization via crossbeam channels (src/collector.rs, src/minipool.rs) handles multi-threaded frame processing.

Content creators, video editors, and developers who need to convert videos or image sequences into high-quality animated GIFs for web sharing. Also used by developers integrating GIF encoding into other applications via the C API (gifski.h) or Rust library interface.

Production-ready. Version 1.34.0 with active maintenance (Dependabot configured in .github/workflows/), CI/CD pipelines for Rust and WebAssembly builds in place, comprehensive test images in tests/ directory (1.png, 2.png, 3.png, a2/ sequence), and Rust 1.74+ requirement indicating modern toolchain adoption. Widely distributed via Homebrew and release binaries.

Low risk for core functionality. Dependencies are well-established (imagequant 4.3.4, gif 0.13.1, resize 0.8.8 with rayon parallelization), but single maintainer (Kornel) is a potential bus-factor concern. AGPL-3.0-or-later license may restrict commercial use without careful review. WebAssembly support adds platform complexity (wasm-bindgen, web-sys dependencies).

Active maintenance with Dependabot enabled (.github/dependabot.yml). Workflows for Rust and WebAssembly builds active (rust.yml, wasm.yml). Latest version 1.34.0 reflects ongoing development. macOS project file (gifski.xcodeproj) and Linux snapcraft config suggest cross-platform distribution focus.

git clone https://github.com/ImageOptim/gifski.git
cd gifski
cargo build --release
./target/release/gifski --help

Or install via Homebrew: brew install gifski. Or Cargo: cargo install gifski --features binary.

Daily commands: CLI: gifski -o output.gif input.png (PNG frames) or ffmpeg -i video.mp4 -f yuv4mpegpipe - | gifski -o output.gif - (video piping). Library: cargo build --lib for Rust library; C bindings auto-generated by cbindgen (cbindgen.toml config). WebAssembly: cargo build --target wasm32-unknown-unknown --features wasm with wasm-bindgen post-processing.

• src/lib.rs — Core library interface and main encoding orchestration; all GIF creation flows start here
• src/encoderust.rs — Primary GIF encoding engine using libimagequant for palette generation and frame processing
• src/collector.rs — Frame collection and temporal dithering coordination; essential for cross-frame quality optimization
• src/c_api.rs — C FFI bindings that expose Rust library to C/C++ consumers; critical for interoperability
• src/bin/gifski.rs — CLI entry point handling argument parsing and user-facing command invocation
• Cargo.toml — Dependency management and feature flags (binary, C API, WASM); defines build configuration

Add a new input video source format

1. Create new source struct implementing the Source trait in src/bin/source.rs (src/bin/source.rs)
2. Implement frame reading logic (e.g., src/bin/ffmpeg_source.rs as reference) (src/bin/[new_format]_source.rs)
3. Register source in CLI input parsing within src/bin/gifski.rs (src/bin/gifski.rs)
4. Add dependency to Cargo.toml and expose via feature flag if optional (Cargo.toml)

Extend C API with new encoding option

1. Add configuration field to GifskiSettings struct in src/c_api.rs (src/c_api.rs)
2. Update C API documentation and regenerate header with cbindgen (cbindgen.toml)
3. Thread parameter through encoderust.rs encoding functions (src/encoderust.rs)
4. Add corresponding Rust API parameter to src/lib.rs public interface (src/lib.rs)

Optimize frame processing quality

1. Adjust quantization or dithering parameters in src/collector.rs (src/collector.rs)
2. Modify frame sampling or preprocessing in src/encoderust.rs (src/encoderust.rs)
3. Add denoise preprocessing if needed via src/denoise.rs (src/denoise.rs)
4. Test with test images in tests/a2/ and tests/a3/ directories (tests/tests.rs)

Add progress callback for UI integration

1. Define callback type and integrate into src/progress.rs (src/progress.rs)
2. Thread callback through src/lib.rs public API (src/lib.rs)
3. Emit progress events from src/collector.rs during encoding (src/collector.rs)
4. Expose via C API in src/c_api.rs if needed for C consumers (src/c_api.rs)

• libimagequant (via imagequant crate) — Provides sophisticated palette generation and dithering; handles cross-frame color optimization to maximize quality within GIF's 256-color-per-frame constraint
• Rust + FFI/C API — Memory safety and performance critical for video processing; C bindings enable use in native applications (macOS, Windows, Linux tools)
• FFmpeg integration (optional) — Universal video format support without reimplementing decoders; users can supply raw frame sequences or video files
• WebAssembly (WASM) — Enables browser-based GIF generation without server infrastructure; compiled once, runs on any platform with wasm-pack
• gifsicle post-processing — Further optimizes GIF file size and animation smoothness via Lzw compression and frame optimization

• GIF format (256 colors/frame max) vs. modern video codecs

  • Why: GIF is universally supported, no playback plugins needed; acceptable quality loss justified by ubiquity
  • Consequence: Quality floor is bounded by 256-color limit; aggressive dithering and palette optimization necessary

• Multi-threaded frame processing with minipool vs. single-threaded

  • Why: Video encoding is CPU-intensive; parallelization amortizes quantization cost across frames
  • Consequence: Synchronization overhead; must carefully batch frames to avoid contention

• Temporal dithering (cross-frame) vs. per-frame dithering

  • Why: Human eye perceives flicker at frame boundaries; spreading dithering pattern across time reduces banding
  • Consequence: Requires frame lookahead and coordination; more complex collector logic

• Rust library + C FFI instead of pure C

  • Why: Rust's memory safety and high-level abstractions reduce bugs; FFI allows safe interop with C/C++ apps
  • Consequence: Slightly larger binary; requires cbindgen tooling for header generation

• Real-time GIF encoding (batch processing only; no streaming)
• Lossless GIF (always quantizes to 256 colors/frame)
• Audio support (video frames only, no soundtrack)
• Interactive parameter tuning UI (CLI-driven; GUI is separate project)
• Cross-platform GUI (CLI tool; separate gifski-app provides GUI)

1. AGPL-3.0-or-later license: Linking to gifski as a library requires GPL/AGPL-compatible licensing or obtaining a commercial license from ImageOptim. 2. Feature flags required: cargo build without --features binary won't produce the CLI tool; C library requires no special features but depends on cbindgen for header generation. 3. FFmpeg optional: --features ffmpeg needed for ffmpeg_source.rs; Y4M support requires --features y4m. 4. Minimum Rust 1.74+: Explicitly set in Cargo.toml; older toolchains will fail. 5. rayon parallelization: resize crate uses rayon; respects RAYON_NUM_THREADS env var for thread count control.

• Temporal Dithering — gifski's core advantage over naive GIF encoders; dithering varies across frames to trade temporal flicker for perceived color depth within GIF's 256-color limit, essential to understand quality tradeoffs
• Cross-Frame Palettes — gifski builds a single global color palette optimized across all input frames rather than per-frame palettes; this is why it wraps imagequant rather than using standard quantization
• Y4M (YUV4MPEG2) — Intermediate video format used by ffmpeg piping to gifski; understanding YUV chroma subsampling and channel layout explains why frame downsampling helps hide codec artifacts
• Rayon Data Parallelism — resize crate uses rayon for parallel image scaling; gifski's throughput depends on understanding work-stealing thread pools and how crossbeam channels coordinate with rayon workers
• cbindgen Code Generation — C header (gifski.h) is auto-generated from Rust source; modifying src/c_api.rs requires regenerating headers via cbindgen, a non-obvious build step for C consumers
• Crossbeam Channel Backpressure — src/collector.rs uses bounded channels to synchronize frame input, quantization, and GIF output stages; backpressure prevents memory exhaustion on large videos, critical for streaming architectures
• WebAssembly WASI/wasm-bindgen — gifski can compile to WebAssembly via wasm-bindgen and wasm32-unknown-unknown target; requires understanding JS bindings, memory model differences, and rayon compatibility via wasm-bindgen-rayon

• ImageOptim/pngquant — Parent project; gifski wraps imagequant (the pngquant color quantization library) as its core palette generation engine
• jnordberg/gif — gif crate used for low-level GIF encoding; understanding its frame/palette API helps debug rendering issues in gifski
• ImageOptim/ImageOptim — Companion desktop application family; ImageOptim integrates gifski for GIF export workflows
• xiph/theora — Alternative video codec for lossless frame capture; ffmpeg-next in gifski supports Theora as a video input source
• sindresorhus/gifski-app — Official macOS GUI wrapper for gifski CLI; demonstrates production usage patterns and user experience expectations

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 integration tests for multi-frame GIF encoding with quality validation

The tests/ directory contains only PNG and frame sequence samples (tests/a2/) but lacks actual integration tests that verify GIF encoding quality, frame timing, and palette optimization. Given that gifski's core value proposition is 'squeezes maximum possible quality from the awful GIF format', there should be automated tests validating encoding output against baseline GIFs. This would catch regressions in quality metrics, color accuracy, and animation smoothness.

• [ ] Create tests/integration_tests.rs with test functions that encode tests/a2/ frames into a GIF
• [ ] Use the public API from src/lib.rs (Collector, Context) to encode test frames
• [ ] Add baseline GIF files to tests/ directory for comparison
• [ ] Implement quality metrics validation (e.g., frame count, color palette size, frame timing)
• [ ] Add CI step to .github/workflows/rust.yml to run these integration tests

Add comprehensive benchmarks for encoding performance across different input types

The repo supports multiple input sources (ffmpeg_source.rs, gif_source.rs, png.rs, y4m_source.rs) and quality settings, but has no benchmarks to track encoding performance. New contributors or performance-conscious users have no way to validate improvements or regressions. Benches would help justify optimization PRs and provide baselines for various input formats.

• [ ] Create benches/ directory with benches/encoding.rs
• [ ] Add benchmark tests for PNG sequence encoding (using tests/a2/ frames)
• [ ] Add benchmark tests for different quality levels via src/lib.rs Config
• [ ] Add benchmark for frame collection speed using src/collector.rs
• [ ] Document in README.md how to run benchmarks with cargo bench
• [ ] Consider adding benchmark tracking to .github/workflows/rust.yml

Add platform-specific documentation and CI for WebAssembly build in README.md

The repo has src/wasm.rs, .github/workflows/wasm.yml, and wasm-bindgen dependencies, but the README.md (which is truncated in the provided snippet) likely lacks instructions for building/using the WASM variant. New contributors cannot easily discover or test WASM functionality. The wasm.yml workflow exists but lacks visibility in the main documentation.

• [ ] Extend README.md with a 'WebAssembly' section documenting WASM build steps
• [ ] Document wasm-bindgen API signatures exported from src/wasm.rs
• [ ] Add code example showing how to use gifski in a browser via the WASM build
• [ ] Reference the wasm.yml workflow and explain feature flags (wasm feature)
• [ ] Add a note about wasm-bindgen-rayon for parallel processing in WASM context

• Add integration tests in tests/ for the C API (gifski.h) by creating a small .c test file and linking against libgifski; currently only Rust tests exist.
• Document the denoise algorithm in src/denoise.rs with inline code comments explaining the temporal filtering logic and parameters (currently sparse).
• Create an example in examples/ showing how to use gifski as a library from Rust code with a minimal frame sequence → GIF workflow (README only covers CLI usage).

The gifski codebase demonstrates generally good security practices with modern Rust tooling and memory-safety guarantees. However, key concerns include: (1) AGPL licensing implications for commercial integrations, (2) reliance on external dependencies (especially FFmpeg) without apparent security scanning in CI, (3) potential race conditions in multi-threaded code, and (4) expanded attack surface from WASM compilation.

• High · AGPL-3.0-or-later License Compliance Risk — Cargo.toml (license field), src/c_api.rs. The project is licensed under AGPL-3.0-or-later, which requires that any modifications and derivative works must be released under the same license and made available to users. This creates legal and compliance risks for proprietary or closed-source integrations, especially when used as a C library or embedded in other applications. Fix: Clearly document the AGPL license terms for users integrating this as a library. Consider dual-licensing if business requirements demand it. Ensure all derivative works comply with AGPL obligations.
• Medium · Unverified External Dependencies — Cargo.toml (dependencies section). The project depends on external crates like 'ffmpeg-next' (version 8), 'imagequant' (4.3.4), and others without explicit security audit or lock file verification in CI/CD. These dependencies could introduce vulnerabilities if compromised or poorly maintained. Fix: Implement dependency scanning tools (cargo-audit, cargo-deny) in CI/CD pipeline. Pin critical dependencies to specific versions with checksum verification. Regularly audit and update dependencies. Use 'cargo vendor' for offline builds when possible.
• Medium · FFmpeg Integration Without Validation — src/bin/ffmpeg_source.rs, Cargo.toml (ffmpeg dependency). The ffmpeg-next dependency is optional but when enabled (in src/bin/ffmpeg_source.rs), it processes untrusted media input without apparent validation. FFmpeg has a history of security vulnerabilities in parsing malformed files. Fix: Implement strict input validation for media files before passing to FFmpeg. Run FFmpeg in a sandboxed environment (container or seccomp) when processing untrusted inputs. Add timeout limits for FFmpeg operations.
• Medium · Unsafe Rayon Parallelization — Cargo.toml (resize with rayon, wasm-bindgen-rayon), src/minipool.rs. The project uses 'wasm-bindgen-rayon' and 'resize' with rayon features for parallel processing. While Rust's safety guarantees mitigate many issues, improper synchronization in custom code could lead to race conditions or data corruption. Fix: Audit src/minipool.rs and any custom thread pool code for potential race conditions. Use ThreadSanitizer (TSAN) in testing. Ensure all shared state is properly protected with synchronization primitives.
• Low · WASM Security Surface — src/wasm.rs, Cargo.toml (wasm-bindgen, web-sys features). The project includes WebAssembly compilation support (src/wasm.rs, wasm-bindgen) which expands the attack surface. WASM running in browsers has different security constraints than native code. Fix: Implement proper CORS headers when serving WASM. Validate all input from JavaScript/browser context. Use Content Security Policy (CSP). Test WASM build separately from native builds. Document WASM security limitations.
• Low · Incomplete Dependency Specification — Cargo.toml (ffmpeg dependency features). The ffmpeg dependency specification in Cargo.toml appears truncated/incomplete (features section cuts off), which could indicate incomplete configuration or build issues. Fix: Complete and verify the ffmpeg dependency configuration. Explicitly list all required features. Test compilation with and without optional features to ensure robustness.
• Low · Test Data Exposure — tests/ directory, Cargo.toml (include field). The tests directory contains 43+ PNG test files that may be included in distributions. While typically benign, this increases package size and potential supply chain attack surface. Fix: Verify that test data is excluded from published crates. Update Cargo.toml include field to explicitly exclude tests/. Document why test images are necessary for distribution.

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.