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/liuliu/ccv 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 today
• 2 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ 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 liuliu/ccv repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/liuliu/ccv.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "liuliu/ccv(\\.git)?\\b" \\
  && ok "origin remote is liuliu/ccv" \\
  || miss "origin remote is not liuliu/ccv (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 unstable >/dev/null 2>&1 \\
  && ok "default branch unstable exists" \\
  || miss "default branch unstable no longer exists"

# 4. Critical files exist
test -f "README.rst" \\
  && ok "README.rst" \\
  || miss "missing critical file: README.rst"
test -f "WORKSPACE" \\
  && ok "WORKSPACE" \\
  || miss "missing critical file: WORKSPACE"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "bin/nnc/.ycm_extra_conf.py" \\
  && ok "bin/nnc/.ycm_extra_conf.py" \\
  || miss "missing critical file: bin/nnc/.ycm_extra_conf.py"
test -f "LEARNINGS.md" \\
  && ok "LEARNINGS.md" \\
  || miss "missing critical file: LEARNINGS.md"

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

ccv is a portable, minimalist C-based computer vision library designed for production deployment with built-in cache mechanisms for transparent image preprocessing. It implements state-of-the-art algorithms for image classification, face detection, object detection (pedestrians/cars), text detection, and long-term object tracking, while maintaining zero dependencies for most features (except BLAS for convolutional networks). Monolithic core library (lib/ccv*.c) with modular algorithm implementations (e.g., bin/bbfcreate.c for cascade classifiers, bin/cnnclassify.c for neural networks). Separate bin/cuda/ subtree for CUDA kernels. Bazel build system (WORKSPACE, BUILD, bazel/) coexists with traditional Makefile. Tools in bin/ (Ruby, C, shell) wrap algorithms for CLI usage.

Systems engineers and performance-critical application developers deploying computer vision on embedded systems (Raspberry Pi, iOS, Android), servers, or resource-constrained environments who need portable, battle-tested algorithms without heavyweight framework overhead.

Production-ready and actively maintained since 2010. Comprehensive CI/CD across Ubuntu, macOS (Intel + ARM64), Raspberry Pi 4, CUDA, and UBSan with coverage tracking (.github/workflows/*.yaml). The codebase spans 86MB C++, 26MB C, CUDA support, and multiplatform binaries (bin/) indicate stable, deployable status.

Single-maintainer (liuliu) risk is moderate given project longevity and CI robustness. Primary risk: tight coupling to low-level C/C++ means API changes break compiled binaries. CUDA support (bin/cuda/*.cu) adds compilation complexity. No visible package manager integration beyond Swift Package Manager (Package.swift), limiting ecosystem reach.

Active development on tensor operations and Apple platform optimization (.agents/skills/tensor-op-apple.md), platform benchmarking infrastructure, and Bazel build modernization. GitHub Actions pipelines test against Ubuntu, macOS ARM64, Raspberry Pi 4, and CUDA. Deep learning via libnnc.org companion library.

git clone https://github.com/liuliu/ccv.git
cd ccv
make -C lib
# or with Bazel:
bazel build //lib:ccv

See Makefile in root and bin/cuda/makefile for platform-specific builds.

Daily commands: Build static lib: make -C lib or bazel build //lib:ccv. Run benchmarks: bazel run //bin/bench:layer_norm_bench (CUDA). CLI tools: ./bin/cnnclassify [image] after building bin/ targets. CUDA tests: .github/workflows/cuda-int-tests.yaml shows exact setup.

• README.rst — Core project vision and capabilities; explains the minimalist C-based design philosophy and cross-platform support that defines ccv's architectural choices.
• WORKSPACE — Bazel build configuration root; essential for understanding the monorepo structure and how dependencies are orchestrated across platform-specific builds.
• Package.swift — Swift Package Manager configuration showing ccv's multi-language bindings strategy and how the library integrates with Apple ecosystems.
• bin/nnc/.ycm_extra_conf.py — Neural Network Compiler (NNC) configuration entry point; reveals the build system for deep learning models and GPU acceleration paths.
• LEARNINGS.md — Design decisions and lessons learned document; critical for understanding why certain architectural patterns were chosen over alternatives.
• bin/mfa/makefile — Metal For Apple (MFA) GPU kernel build system; shows Apple-specific tensor operation acceleration strategy for ARM64 platforms.
• .github/workflows/ubuntu-unit-tests.yaml — Primary CI/CD pipeline definition; illustrates test coverage strategy across the codebase and integration validation approach.

Add a new GPU-accelerated tensor operation

1. Define the operation signature in the NNC compiler grammar (bin/nnc/gemm_kernel_gen.cpp)
2. Implement CUDA kernel variant in the GPU acceleration layer (bin/cuda/cwc-forwards-runtime.cu)
3. Implement Metal For Apple kernel variant for ARM64 support (bin/mfa/implicit_conv3d_bench.cpp)
4. Add cuDNN backend implementation for NVIDIA optimization (bin/nnc/cudnn/conv-cudnn-forw.c)
5. Register benchmarking test in the performance suite (bin/bench/layer_norm_bench.cu)
6. Add cross-platform unit test to CI/CD workflow (.github/workflows/cuda-int-tests.yaml)

Add support for a new dataset format

1. Create dataset loader following CIFAR-10 pattern (bin/cifar-10.c)
2. Implement preprocessing pipeline in NNC framework (bin/nnc/csv.c)
3. Add training harness referencing ImageNet example (bin/image-net.c)
4. Register dataset in Bazel build configuration (BUILD)
5. Add validation tests to CI/CD (.github/workflows/ubuntu-unit-tests.yaml)

Optimize a kernel for a new platform

1. Profile current performance using benchmarking harness (bin/mfa/gemm_kernel_introspect.cpp)
2. Implement platform-specific kernel (e.g., Apple Metal) (bin/mfa/na_attention_backward_bench.cpp)
3. Register in Metal For Apple build system (bin/mfa/makefile)
4. Add platform validation to CI/CD pipeline (.github/workflows/macos-arm-unit-tests.yaml)
5. Document optimization insights (MFADecoding.md)

Add a new classical vision detector (BBF, DPM, or ICF)

1. Implement detector algorithm following DPM pattern (bin/dpmdetect.c)
2. Create model training tool (bin/dpmcreate.c)
3. Add visualization/validation script (bin/dpmvldtr.rb)
4. Register in top-level build configuration (bin/makefile)
5. Add detector to CI/CD unit tests (.github/workflows/ubuntu-unit-tests.yaml)

• C (core language) — Maximum portability and embeddability across diverse platforms (mobile, embedded, servers) with minimal runtime overhead; aligns with original 2010 minimalism design philosophy.
• Bazel (build system) — Enables hermetic, reproducible builds across 8+ platforms (Linux x64, macOS ARM/x64, Raspberry Pi, Windows, iOS, Android) with fine-grained dependency tracking and GPU compilation support.
• CUDA & Metal For Apple — Leverage specialized GPU ISAs for 10-100x acceleration of tensor operations; Metal required for Apple Silicon (ARM64) which uses non-CUDA architecture.
• cuDNN (NVIDIA backend) — Provides highly optimized deep learning primitives for NVIDIA GPUs; reduces need to write hand-tuned kernels for common operations.
• Neural Network Compiler (NNC) — Custom JIT compiler for dynamic computation graphs enables shape inference, kernel fusion, and platform-specific code generation without external dependencies.

• C instead of C++/Python

  • Why: Minimize external dependencies and runtime complexity for embedded deployment (Raspberry Pi, IoT devices) and maximize ABI stability.
  • Consequence: Requires manual memory management; no generics/templates; steeper learning curve for modern developers; smaller ecosystem of libraries.

• Custom NNC compiler instead of TensorFlow/PyTorch

  • Why: Avoid heavy runtime dependencies and enable on-device compilation for mobile
  • Consequence: undefined

1. BLAS dependency is conditional—many algorithms work without it, but convnets silently degrade. Set CBLAS library in Makefile if classification fails. 2. Image cache is automatic but memory-intensive; no explicit purge API—long-running processes may leak if reprocessing same images repeatedly. 3. CUDA builds require nvcc + separate Makefile path (bin/cuda/makefile); mismatched CUDA versions between compile and runtime cause silent kernel failures. 4. C API lacks thread safety guarantees on shared detector objects—detectors must be per-thread. 5. macOS ARM64 uses different Accelerate framework; build flags in .github/workflows/macos-arm-unit-tests.yaml are non-obvious.

• Deformable Parts Model (DPM) — Core algorithm in lib/ccv_dpm.c for pedestrian/car detection; understanding part-based representations is essential to extending object detection
• Cascade Classifiers (Viola-Jones/ICF) — Implements fast face detection in lib/ccv_icf.c via boosted weak classifiers; fundamental to real-time inference on embedded systems
• Image Pyramid & Scale-Space — Built into ccv's transparent preprocessing cache; enables multi-scale detection without redundant recomputation
• BLAS/CBLAS Linear Algebra — Optional but critical dependency for CNN convolution (lib/ccv_convnet.c); understanding BLAS calls is needed to optimize inference
• CUDA Kernel Warp Scheduling — bin/cuda/ kernels use shared memory and warp-aware loops; understanding SM occupancy is key to debugging GPU performance bottlenecks
• Dense SIFT & Feature Extraction — Used by tracking and feature matching in lib/ccv_sift.c; dense grid-based features differ from sparse Harris corners
• Transparent Caching / Memoization — Core design principle in ccv: preprocessing results cached transparently behind API; understanding cache coherency prevents silent correctness bugs

• opencv/opencv — Heavyweight alternative with more algorithms and language bindings, but heavier dependencies—ccv targets minimal deployment footprint
• thorvald/simd-opencv — SIMD-optimized vision kernels; ccv could benefit from porting key inner loops for single-platform perf
• liuliu/libnnc — Companion deep learning library (referenced as https://libnnc.org); handles neural network training that ccv_convnet.c loads
• Homebrew/homebrew-core — ccv package (if present) shows macOS deployment practices; understanding Homebrew formula helps with ARM64 cross-compilation
• bazelbuild/bazel — Build system used in WORKSPACE/BUILD; ccv's Bazel migration shows modern C++ monorepo patterns

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 unit tests for MFA (Metal For Apple) tensor operations

The repo has extensive MFA (Metal For Apple) implementation in bin/mfa/ with files like attention_backward_compare_probe.cpp, conv3d_kernel_bench.cpp, and dump_na_int8_attention_source.cpp, but there's no dedicated GitHub Actions workflow for MFA validation. Given the .github/workflows/macos-arm-unit-tests.yaml and macos-unit-tests.yaml exist, adding a specific MFA test suite would ensure Metal-accelerated operations work correctly across Apple platforms and catch regressions early.

• [ ] Create .github/workflows/macos-mfa-validation.yaml workflow file
• [ ] Add unit test targets in bin/mfa/ directory that validate attention operations, conv3d kernels, and int8 quantized operations
• [ ] Reference the existing macos-arm-unit-tests.yaml structure but add MFA-specific validation steps
• [ ] Ensure tests cover both attention_backward_compare_probe and conv3d_kernel_bench scenarios

Add Windows CI/CD pipeline with comprehensive build validation

The README mentions 'Windows*' (with asterisk, implying incomplete support) and the .github/workflows directory has coverage for Ubuntu, macOS, Raspberry Pi, and CUDA, but NO Windows workflow exists. The presence of Windows in the README suggests it's a stated goal but untested. Adding a Windows GitHub Actions workflow would validate cross-platform builds and catch Windows-specific compilation errors early.

• [ ] Create .github/workflows/windows-unit-tests.yaml using GitHub Actions windows-latest runner
• [ ] Reference the existing ubuntu-unit-tests.yaml and macos-unit-tests.yaml as templates
• [ ] Add Windows-specific build steps (likely using MSVC or MinGW based on existing build infrastructure)
• [ ] Validate that core tests pass and document any Windows-specific limitations in WORKLOG.rst

Document and add integration tests for CUDA backend and backward compatibility

The repo has extensive CUDA support (bin/cuda/ directory with cwc-backwards.c, cwc-forwards.c, cwc-verify.c) and a cuda-int-tests.yaml workflow, but there's no clear documentation in README.rst or a dedicated LEARNINGS.md section explaining CUDA setup, versioning requirements, or backward compatibility guarantees. The LEARNINGS.md file exists but likely doesn't cover this. Adding tests that validate CUDA+CPU parity (comparing cwc-verify-runtime.cu outputs) would ensure numerical correctness.

• [ ] Enhance .github/workflows/cuda-int-tests.yaml to include additional verification steps comparing CUDA and CPU results from cwc-verify.c
• [ ] Create a CUDA_SETUP.md document explaining CUDA version requirements, device compatibility, and fallback behavior
• [ ] Add regression tests in bin/cuda/makefile that validate backward pass matches forward pass numerically within tolerance
• [ ] Update README.rst CUDA section with link to CUDA_SETUP.md and performance expectations

• Add Python bindings for text detection (lib/ccv_text.c exists but bin/ has no text_detect.py wrapper like cnnclassify.py), enabling easier evaluation on datasets
• Expand CUDA benchmark suite beyond layer_norm_bench.cu—add convolution, pooling benchmarks in bin/bench/*.cu with reporting to match platform-benchmark-skill.md
• Document cache invalidation patterns in LEARNINGS.md; currently undocumented and causes confusion when preprocessing parameters change (no API to clear ccv's internal preprocessing cache)

The ccv repository shows a moderate security posture. As a C-based computer vision library with support for GPU acceleration (CUDA), the primary concerns are memory safety issues common to C programs, GPU security implications, and model integrity validation. The codebase appears to have comprehensive CI/CD pipeline (multiple GitHub Actions workflows for unit tests, coverage, and analysis) which is positive. However, the absence of visible security documentation, lack of dependency transparency, and inherent risks of C memory management warrant attention. No hardcoded secrets or obvious configuration mismanagement was detected from the file structure alone. Regular static analysis (Clang Analyzer is already integrated), fuzzing of input handling functions, and security-focused code reviews are recommended.

• Medium · Potential Buffer Overflow in C Code — bin/*.c files, core library C implementation. The codebase is written in C (as indicated by .c files throughout bin/ and core library). C programs are susceptible to buffer overflow vulnerabilities if input validation and bounds checking are not properly implemented. Files like bin/aflw.c, bin/bbfdetect.c, and bin/dpmdetect.c suggest image processing with external data inputs, which are common attack vectors. Fix: Conduct thorough code review of all C functions handling external input. Use static analysis tools (Clang Static Analyzer, Coverity). Implement bounds checking for all buffer operations. Consider using safe string handling functions and memory safety tools.
• Medium · Missing CUDA Security Hardening — bin/cuda/*.cu, bin/bench/layer_norm_bench.cu. Multiple CUDA files (.cu) are present in bin/cuda/ and bin/bench/ directories. GPU memory management and CUDA kernels can have security implications including information leakage and side-channel attacks if not properly isolated. Fix: Review CUDA code for memory access patterns and potential information disclosure. Ensure GPU memory is properly cleared after use. Implement access controls for GPU resources if handling sensitive data.
• Medium · Unvalidated Model File Loading — bin/alex_model.inc, bin/matt_models.inc, bin/*detect.c, bin/*classify.c. Files like bin/alex_model.inc, bin/matt_models.inc, and various bin/*detect.c and bin/*classify.c files suggest loading pre-trained models from files. If model files are not cryptographically verified or properly validated, attackers could perform model poisoning attacks. Fix: Implement cryptographic signature verification for all model files. Use checksums (SHA-256) to detect tampering. Store models in read-only locations when deployed. Document model provenance and validation procedures.
• Low · Build Configuration Exposure — bazel/*, BUILD, WORKSPACE, bazel/setup_clang.sh. The presence of build configuration files (bazel/sample.bazelrc, BUILD, WORKSPACE) and setup scripts (bazel/setup_clang.sh) in the repository could potentially expose build-time secrets or internal development paths if not properly cleaned. Fix: Ensure build configuration files do not contain credentials, API keys, or internal paths. Use environment variables for sensitive build parameters. Review .gitignore to ensure sensitive files are properly excluded.
• Low · Minimal Dependency Documentation — Package.swift, dependency management files. No Package.swift or dependency lock file content was provided for analysis. The Package.swift file exists but its contents are not shown, making it impossible to verify dependency versions and identify known vulnerable dependencies. Fix: Maintain updated dependency lock files (package-lock.json, Pipfile.lock, Cargo.lock, etc.). Regularly scan dependencies using tools like OWASP Dependency-Check, Snyk, or npm audit. Pin dependency versions and implement automated security updates.
• Low · Missing Security Documentation — Repository root. No SECURITY.md or security policy file is evident in the root directory. This makes it difficult for security researchers to responsibly disclose vulnerabilities. Fix: Create a SECURITY.md file with responsible disclosure guidelines. Include contact information for reporting security issues. Establish a coordinated disclosure process and timeline for addressing reported vulnerabilities.

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.