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/wolfpld/tracy 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 — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 77% 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 wolfpld/tracy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wolfpld/tracy.

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

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

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

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "capture/src/capture.cpp" \\
  && ok "capture/src/capture.cpp" \\
  || miss "missing critical file: capture/src/capture.cpp"
test -f "cmake/options.cmake" \\
  && ok "cmake/options.cmake" \\
  || miss "missing critical file: cmake/options.cmake"
test -f "cmake/vendor.cmake" \\
  && ok "cmake/vendor.cmake" \\
  || miss "missing critical file: cmake/vendor.cmake"
test -f "examples/ToyPathTracer/Source/enkiTS/TaskScheduler.cpp" \\
  && ok "examples/ToyPathTracer/Source/enkiTS/TaskScheduler.cpp" \\
  || miss "missing critical file: examples/ToyPathTracer/Source/enkiTS/TaskScheduler.cpp"

# 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/wolfpld/tracy"
  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).

Tracy is a real-time frame and sampling profiler with nanosecond-resolution telemetry that captures CPU, GPU (OpenGL/Vulkan/D3D/Metal/CUDA), memory allocations, and locks across networked machines. It combines frame profiling (for games/interactive apps) with statistical sampling, allowing developers to analyze performance bottlenecks in C++, C, Python, Lua, and Fortran codebases with minimal overhead. Multi-tool monorepo: core profiler library in Tracy headers/src/, standalone GUI application in profiler/, CLI tools in capture/ (CaptureOutput.cpp, capturedaemon.cpp) and csvexport/, documentation in doc/, with CMake as the primary build system and vendor dependencies managed via cmake/vendor.cmake. The capture suite decouples data collection from visualization, allowing headless profiling on remote/embedded systems.

Game engine developers, graphics programmers, and performance engineers who need to diagnose frame-time issues, GPU stalls, and memory allocation patterns in real-time without stopping execution. Primary users are C++ game developers integrating Tracy macros into their codebase, but also systems programmers profiling low-level performance across heterogeneous architectures (CPU+GPU).

Highly mature and production-ready: active development with v0.8+ releases, comprehensive CI across Windows/macOS/Linux/MinGW/Emscripten (.github/workflows/), extensive TeX documentation (445KB), and established video tutorial series from v0.2 through v0.8. Single-maintainer (wolfpld) but stable API and regular releases indicate long-term commitment.

Low risk for stable use: mature codebase with no emergency breaking changes indicated, but single maintainer (wolfpld) creates potential bottleneck for critical fixes. Dependency footprint is moderate (CPM.cmake for vendor management, imgui/gl3w for UI), and the large C++ codebase (~18MB) means onboarding cost is non-trivial. No visible security audit history, so use caution in security-sensitive applications.

Actively maintained: multiple CI workflows running on every push (linux.yml, macos.yml, windows.yml, emscripten.yml for web builds), latex.yml for doc generation, and release.yml for distribution. Recent work includes Emscripten/web support, platform-specific optimizations, and continued feature expansion across GPU APIs and sampling modes.

Clone the repository and use CMake: git clone https://github.com/wolfpld/tracy.git && cd tracy && mkdir build && cd build && cmake .. && cmake --build . . Windows binaries are available pre-built in the Releases section. For profiling your C++ app, include Tracy headers and link against libtracy, then add ZoneScoped macros to your code.

Daily commands: CMake-based build: run cmake --build . --config Release after configuring with cmake -DCMAKE_BUILD_TYPE=Release .. in a build/ directory. The profiler GUI launches as ./profiler/Tracy (or Tracy.exe on Windows). To profile an app, define TRACY_ENABLE and call ZoneScoped/ZoneNamed macros in your C++ code, then launch the GUI and connect to localhost:8086 (or your remote target).

• CMakeLists.txt — Root build configuration defining project structure, dependencies, and compilation targets for all profiler components across platforms.
• capture/src/capture.cpp — Main capture daemon that collects profiling telemetry from instrumented applications and manages the core data pipeline.
• cmake/options.cmake — Feature flags and build options controlling Tracy's multi-platform, multi-API support (OpenGL, Vulkan, CUDA, Metal, etc.).
• cmake/vendor.cmake — Third-party dependency management (CPM, ImGui, GL3W) defining external library versions and integration points.
• examples/ToyPathTracer/Source/enkiTS/TaskScheduler.cpp — Task scheduling library used throughout examples for parallel workload distribution, foundational to CPU profiling demonstrations.
• .github/workflows/linux.yml — CI pipeline validating Linux builds across architectures, ensuring cross-platform profiler reliability.
• capture/src/CaptureOutput.cpp — Telemetry serialization and output handling, critical for converting profiling events into persistable trace format.

Add Support for a New GPU API

1. Add feature flag in cmake/options.cmake (e.g., TRACY_ENABLE_NEWAPI) (cmake/options.cmake)
2. Create API-specific capture module in capture/src/ with event collection and command submission hooks (capture/src/capture.cpp)
3. Extend capture/src/CaptureOutput.cpp to serialize GPU timeline events for the new API (capture/src/CaptureOutput.cpp)
4. Add CI workflow in .github/workflows/ to validate the new API build on target platform (.github/workflows/linux.yml)
5. Create example in examples/ demonstrating profiling with the new API (examples/OpenCLVectorAdd/OpenCLVectorAdd.cpp)

Add a New Export Format

1. Create new export tool in csvexport/src/ or similar (e.g., jsonexport/src/jsonexport.cpp) (csvexport/src/csvexport.cpp)
2. Implement trace format parser and schema serializer using existing trace definitions (capture/src/CaptureOutput.hpp)
3. Register new export target in root CMakeLists.txt build chain (CMakeLists.txt)
4. Add CI validation step in appropriate workflow (Linux/Windows/macOS) (.github/workflows/linux.yml)

Optimize Capture Performance for High-Throughput Scenarios

1. Profile bottleneck using CPU profiler on capture/src/capture.cpp to identify event collection hotspot (capture/src/capture.cpp)
2. Evaluate lock-free data structures (see examples/ToyPathTracer/Source/enkiTS/LockLessMultiReadPipe.h for patterns) (examples/ToyPathTracer/Source/enkiTS/LockLessMultiReadPipe.h)
3. Implement circular buffer or ring queue optimization in telemetry path (capture/src/CaptureOutput.cpp)
4. Benchmark and validate improvement using bundled examples (e.g., examples/fibers.cpp) (examples/fibers.cpp)
5. Run full CI suite to ensure no regression on all platforms (cmake/options.cmake)

Improve Platform Support (new OS or Architecture)

1. Add platform detection and feature flags in cmake/options.cmake for the new platform (cmake/options.cmake)
2. Conditionally compile platform-specific code in capture/src/capture.cpp (e.g., OS-specific timer APIs) (capture/src/capture.cpp)
3. Create new CI workflow in .github/workflows/ (e.g., newos.yml) for automated validation (.github/workflows/linux.yml)
4. Update vendor dependency resolution in cmake/vendor.cmake if platform requires special handling (e.g., architecture-specific libraries) (cmake/vendor.cmake)
5. Create proof-of-concept example in examples/ demonstrating the profiler on the new platform (examples/fibers.cpp)

• CMake + CPM — Cross-platform build system supporting Windows (MSVC), Linux (GCC/Clang), macOS (Clang), iOS, and Emscripten with reproducible dependency management.
• C++11/14/17 — High-performance, zero-overhead profiling with nanosecond-resolution timers and lock-free data structures; minimal runtime overhead critical for profiler accuracy.
• Multi-API GPU Support (OpenGL, Vulkan, Direct3D, Metal, OpenCL, CUDA) — Tracy must instrument all major graphics and compute APIs to provide complete frame profiling across game engines and research applications.
• GitHub Actions CI/CD — Automated multi-platform validation (Linux, Windows, macOS, Emscripten, ARM) ensuring profiler correctness across build targets and architectures.
• Binary Ring Buffer + Event Serialization — Efficient circular memory storage for high-frequency events (millions/second) with minimal lock contention; nanosecond timestamps require compact encoding.
• Task — undefined

Several non-obvious gotchas: (1) TRACY_ENABLE must be defined at compile-time; runtime toggling uses TRACY_ON_DEMAND but with different semantics. (2) Default listening port is 8086—network security policies or existing services may block this. (3) GPU profiling requires matching graphics driver versions and explicit initialization per-API (OpenGL/Vulkan/D3D each have different setup rituals). (4) The profiler GUI expects a modern GPU (ImGui + OpenGL 3.2+); embedded/headless systems use CLI csvexport instead. (5) Lua and Python bindings are external; the core repo only supports C/C++/Fortran/OpenCL directly.

• Nanosecond-resolution event timestamping — Tracy's core advantage is capturing sub-microsecond timing with CPU RDTSC or platform timers; understanding clock resolution and drift is critical when debugging frame-time variance or GPU-CPU sync issues
• Frame-based profiling vs. sampling profiling — Tracy uniquely bridges two paradigms: frame-based zones (deterministic, 100% coverage but higher overhead) and sampling (low overhead but statistical). Knowing when to use each is essential for non-intrusive profiling
• Ring buffers and lock-free queues — Tracy uses lock-free data structures to stream profiling events from instrumented threads to the capture buffer without blocking; critical for understanding low overhead and real-time constraints
• GPU command stream instrumentation — Tracy hooks into graphics driver APIs (OpenGL glQueryCounter, Vulkan VkQueryPool, D3D12 queries) to timestamp GPU work; understanding GPU timeline reconstruction is key to correlating CPU and GPU bottlenecks
• Remote telemetry protocol — Tracy uses a custom TCP-based protocol to stream profiling data from instrumented apps to the viewer GUI; knowledge of the wire format is needed for integrating custom transport layers or building alternative consumers
• Memory allocation tracking via hooks — Tracy intercepts malloc/free/new/delete calls to correlate memory usage with frame timelines; essential for diagnosing frame-time hitches caused by GC, allocation fragmentation, or memory pressure
• Context switch tracing — Tracy captures OS-level context switches (via perf on Linux, ETW on Windows) to show when threads are preempted; critical for understanding unexpected frame-time variance in multi-threaded applications

• google/pprof — CPU-focused statistical profiler with similar remote data collection model, but Tracy adds real-time frame profiling and GPU support that pprof lacks
• LLVM/llvm-project — Compiler profiling infrastructure (XRay, SanitizerCoverage) that shares similar instrumentation principles, though Tracy is game-engine-focused with lower latency requirements
• GameTechDev/GFXBench — GPU performance benchmarking suite; Tracy is the inverse—interactive profiling of existing GPU workloads rather than synthetic benchmarks
• BrendanGregg/FlameGraph — Visualization tool for CPU call stacks from perf/systemtap data; Tracy includes equivalent flamegraph views but for frame-level and GPU timelines simultaneously
• ocornut/imgui — Immediate-mode GUI library used by Tracy's profiler application for the interactive viewport and control panels

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 dtl/ (Diff/Sequence library)

The dtl/ directory contains a sophisticated diff/sequence matching library (Diff.hpp, Diff3.hpp, Lcs.hpp, Ses.hpp) that is likely used for frame comparison and analysis in the profiler UI. Currently there are no visible tests for this core algorithmic component. Adding comprehensive unit tests would catch regressions, validate edge cases (empty sequences, large diffs, identical frames), and make it safer for contributors to modify this critical diff logic.

• [ ] Create tests/dtl/CMakeLists.txt to add a test target
• [ ] Write tests/dtl/test_lcs.cpp for Longest Common Subsequence edge cases
• [ ] Write tests/dtl/test_diff.cpp for diff algorithm validation with mock frame data
• [ ] Write tests/dtl/test_ses.cpp for Shortest Edit Script correctness
• [ ] Integrate test target into root CMakeLists.txt and CI workflows (linux.yml, windows.yml, macos.yml)

Add GitHub Actions workflow for WebAssembly/Emscripten builds

The repo has an emscripten.yml workflow file that appears incomplete or not fully integrated. With Tracy being a frame profiler used in game development, WebAssembly builds would allow developers to profile web-based games and applications. A proper CI workflow ensuring Emscripten builds pass on each commit would reduce friction for web developers using Tracy.

• [ ] Review .github/workflows/emscripten.yml and verify it has proper Emscripten SDK setup steps
• [ ] Ensure CMakeLists.txt has -DCMAKE_TOOLCHAIN_FILE pointing to Emscripten emsdk toolchain
• [ ] Add artifact uploads to emscripten.yml for the built wasm modules (tracy-profiler.wasm, tracy-profiler.js)
• [ ] Test the workflow by adding a sample build configuration in cmake/options.cmake for WASM
• [ ] Document the Emscripten build process in README.md with link to generated .wasm artifacts

Add integration tests for capture daemon and CSV export tools

The capture/ and csvexport/ directories contain important CLI tools (capturedaemon.cpp, csvexport.cpp) that are used for remote profiling data collection and analysis export. There are no visible tests validating end-to-end workflows like: capture daemon receiving data → storing traces → csvexport converting them to CSV format. Adding integration tests would catch breakage in the data pipeline and make it safer to refactor these tools.

• [ ] Create tests/integration/CMakeLists.txt for integration test target
• [ ] Write tests/integration/test_csvexport.cpp with a mock .tracy trace file input and CSV output validation
• [ ] Write tests/integration/test_capture_daemon.cpp validating the capture daemon can receive profiling data via network socket and write valid trace files
• [ ] Add test fixtures directory tests/fixtures/ with sample minimal .tracy binary files
• [ ] Integrate into CI workflows (linux.yml, windows.yml) as a separate test stage that validates full capture→export pipeline

• Add unit tests for csvexport/src/csvexport.cpp: currently no test file exists; create tests/csvexport_test.cpp to verify CSV output format and stat aggregation against known profiling data
• Document GPU profiling setup per API in doc/: the TeX docs mention OpenGL/Vulkan/D3D/Metal/CUDA but lack step-by-step initialization examples; add sections with minimal code examples for each graphics API in the public docs
• Extend capture/src/CaptureOutput.hpp to log validation errors: currently validation silently fails; add optional error callback and structured logging to help users debug misconfigured remote profiling sessions

Tracy Profiler codebase shows reasonable security posture for a development tool. Primary concerns are around dependency management (CPM), patch integrity, and network communication security for remote profiling. The project lacks visible hardcoded credentials and SQL/XSS injection risks typical of web applications. Recommendations focus on strengthening supply chain security, validating external dependencies, and ensuring encrypted communication for remote profiling capabilities. Overall, the security risks are moderate and manageable with standard security practices.

• Medium · Third-party dependency management via CPM.cmake — cmake/CPM.cmake, CMakeLists.txt. The project uses CPM (CPM.cmake) for dependency management in cmake/CPM.cmake. CPM downloads dependencies at build time from remote sources. Without version pinning and integrity verification (checksums/signatures), this could lead to supply chain attacks or accidental use of compromised versions. Fix: Ensure all dependencies fetched via CPM have pinned versions and SHA256 checksums. Verify upstream sources are legitimate and use HTTPS. Consider using lock files or vendoring critical dependencies.
• Medium · Potential unsafe binary patches applied during build — cmake/imgui-emscripten.patch, cmake/imgui-loader.patch, cmake/ppqsort-nodebug.patch, cmake/ppqsort-semaphore.patch, cmake/tidy-cmake.patch, cmake/vendor.cmake. Multiple patch files are present in cmake/ directory (e.g., imgui-emscripten.patch, ppqsort-nodebug.patch) that are applied to dependencies during build. If patch application is not validated, malicious patches could be injected. Fix: Verify patch integrity using checksums. Document why each patch is necessary. Review patches for security implications. Consider submitting patches upstream instead of applying custom modifications.
• Low · Emscripten compilation workflow security — .github/workflows/emscripten.yml. The project supports Emscripten compilation (.github/workflows/emscripten.yml). Emscripten introduces JavaScript code generation which could have XSS implications if profiler data is displayed in web-based viewers without proper sanitization. Fix: Ensure any web-based profiler UI properly escapes and sanitizes profiler data. Use Content Security Policy headers. Validate input from profiler captures before rendering.
• Low · Network communication in profiler — capture/src/, profiler UI components (not fully visible). Tracy is described as a 'remote telemetry' profiler, implying network communication between profiled application and profiler. No visible TLS/encryption configuration in file structure. Fix: Implement TLS/SSL encryption for remote profiling connections. Validate and authenticate remote connections. Use certificate pinning for secure deployments. Document security model for remote profiling.
• Low · CUDA example without explicit security review — examples/CUDAGraphRepro/. CUDA examples are included (examples/CUDAGraphRepro/) which involve GPU memory operations. While not directly a vulnerability, GPU profiling could expose sensitive compute patterns. Fix: Document security implications of profiling GPU workloads. Ensure profiler data doesn't leak sensitive algorithm information. Consider adding sanitization for captured GPU data.

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.