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/rr-debugger/rr 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 1w ago
• 25+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 50% 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 rr-debugger/rr repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rr-debugger/rr.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rr-debugger/rr(\\.git)?\\b" \\
  && ok "origin remote is rr-debugger/rr" \\
  || miss "origin remote is not rr-debugger/rr (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 "src/Command.h" \\
  && ok "src/Command.h" \\
  || miss "missing critical file: src/Command.h"
test -f "src/AddressSpace.h" \\
  && ok "src/AddressSpace.h" \\
  || miss "missing critical file: src/AddressSpace.h"
test -f "src/GdbServer.h" \\
  && ok "src/GdbServer.h" \\
  || miss "missing critical file: src/GdbServer.h"
test -f "src/Event.h" \\
  && ok "src/Event.h" \\
  || miss "missing critical file: src/Event.h"
test -f "include/rr/rr.h" \\
  && ok "include/rr/rr.h" \\
  || miss "missing critical file: include/rr/rr.h"

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

rr is a record-and-replay debugger for Linux that captures complete process execution (including threads and child processes) to disk, then allows deterministic replay with reverse-execution capabilities. It extends gdb with efficient backward stepping and integrates hardware performance counters (Intel VTune, PMU) to enable debugging scenarios impossible in real-time, such as reverse watchpoints and time-travel inspection of program state. Monolithic C/C++ project with include/rr/rr.h as the public API. Core recording/replay engine lives in src/ (inferred from standard rr structure), CMake-based build system (CMakeLists.txt), test suite integrated via CTest (.buildkite/CTestCostData.txt tracks test costs), and release infrastructure under release-process/ with distro-specific JSON configs. Scripts in scripts/ handle symbol collection (rr-collect-symbols.py) and GDB integration (rr-gdb-script-host.py). Build artifacts validated across Alpine, Android, and Ubuntu via GitHub Actions workflows.

Systems engineers, Mozilla developers, and security researchers debugging complex multi-threaded C/C++ applications on Linux. Users need deterministic reproduction of race conditions, heap corruption, or timing-dependent bugs that are difficult to reproduce manually. Sponsored by Pernosco and originated at Mozilla.

Production-ready and actively maintained. The codebase is substantial (2.7M lines C++, 1.2M lines C) with CI via GitHub Actions (.github/workflows/build-and-test-main.yml), organized test infrastructure (.buildkite/pipeline.yml with Julia-based orchestration), and support for multiple Linux distributions via release-process/distro-configs/. The project has been actively developed since Mozilla's sponsorship with continuous CI/CD pipeline validation.

Low risk for mature use cases but hardware-dependent: requires Intel Nehalem+ (2010+), AMD Zen+, or ARM Neoverse N1 CPUs with working PMC virtualization—many cloud VMs and containers lack this. The codebase is large and tightly coupled to kernel APIs (ptrace, performance counters), making updates to Linux kernel behavior potentially breaking. Single maintainer risk is mitigated by Pernosco sponsorship, but the project has strict CPU/kernel requirements limiting portability.

Active CI pipeline testing across multiple platforms (alpine-build.yml, android-build.yml, build-and-test-main.yml). Release process is being managed with distribution-specific configs for Debian 11/12, Ubuntu 20 LTS/22 LTS/24 LTS/24.10, and CentOS 9. Julia-based test orchestration in .buildkite/ suggests recent investment in test infrastructure. The presence of Android builds indicates platform expansion efforts.

Clone and build with standard CMake workflow: git clone https://github.com/rr-debugger/rr.git && cd rr && cmake . && make && sudo make install (or review installation instructions). Alternatively, use the Vagrantfile: vagrant up to get a pre-configured Linux VM with all dependencies. Verify installation with rr --help.

Daily commands: No traditional 'dev server'—this is a CLI tool. Run rr record <command> to record execution (e.g., rr record ./myapp), which creates a trace in ~/.local/share/rr/. Then replay with rr replay and interact via embedded gdb session. For development: cmake . && make to build, ctest (via CTest infrastructure in .buildkite/) to run tests.

• src/Command.h — Base command interface that all rr subcommands inherit from; essential for understanding the plugin/command architecture
• src/AddressSpace.h — Core abstraction for process virtual memory management; fundamental to replay and record mechanisms
• src/GdbServer.h — Implements the GDB protocol server that enables debugger integration and reverse-execution features
• src/Event.h — Represents recorded events (syscalls, signals, etc.) that form the backbone of the record/replay trace
• include/rr/rr.h — Public C API header; defines the stable interface for external tools and libraries using rr
• CMakeLists.txt — Build configuration; required to understand dependencies, compilation flags, and platform-specific handling
• src/Flags.h — Global configuration and command-line flag management; used throughout the codebase for feature toggling

Add a New rr Subcommand

1. Create a new command class inheriting from Command in src/YourCommand.h (src/Command.h)
2. Implement command logic in src/YourCommand.cc with parse_args() and run() methods (src/Command.cc)
3. Register the command in the main command dispatch (typically in main command factory) (src/Command.cc)
4. Add help text and flags to Flags.h if command accepts CLI arguments (src/Flags.h)

Add a New GDB Protocol Extension

1. Define the extension packet structure and handler in src/GdbServer.h (src/GdbServer.h)
2. Implement packet parsing and response in src/GdbServerConnection.cc (src/GdbServerConnection.cc)
3. Register the handler in the packet dispatch table (src/GdbServer.cc)
4. Add unit tests or integration tests in test suite (src/DebuggerExtensionCommand.h)

Add Support for a New Syscall or Event Type

1. Define the new event type in src/Event.h enum (src/Event.h)
2. Implement syscall interception and recording in appropriate monitor (FileMonitor, etc.) (src/FileMonitor.h)
3. Add replay logic in src/Event.cc to handle the event during replay (src/Event.cc)
4. Update serialization in CompressedWriter/CompressedReader if needed (src/CompressedWriter.cc)

Add CPU Feature Detection or Workaround

1. Add feature detection logic in src/CPUs.cc with appropriate CPUID checks (src/CPUs.cc)
2. Define the feature constant in src/CPUs.h (src/CPUs.h)
3. Implement microcode or execution workaround in relevant replay path (src/CPUIDBugDetector.h)
4. Add conditional logic using feature flag in record/replay hot paths (src/Event.cc)

• ptrace (Linux syscall tracing) — Enables lightweight syscall interception and process control without kernel modifications; fundamental to rr's record mechanism
• Zstandard compression — Reduces trace file size by 5–10x; balances compression ratio and replay speed for practical deployability
• GDB Remote Serial Protocol — Allows any GDB-compatible debugger (lldb, vscode, etc.) to connect; decouples rr from specific debugger UIs
• DWARF debug symbols — Enables source-level debugging and variable inspection without modifying binaries
• x86-64 hardware breakpoints/watchpoints — Efficient breakpoint/watchpoint evaluation during replay without recompilation
• Custom event log format — Optimized binary format balances serialization overhead and replay performance

• Heavyweight record (full syscall logging) vs. lightweight sampling
  • Why:
  • Consequence: undefined

Hardware requirement is non-negotiable: code will silently fail or crash on unsupported CPUs (no graceful fallback). Kernel version >= 4.7 required for __WALL support in waitid()—older systems need rr 5.6.0. PMC virtualization must be enabled in VM guests; Xen is explicitly unsupported. The trace format is not versioned in obvious places; upgrading rr may break replay of old traces. Building with certain compiler flags or glibc versions can cause subtle record/replay divergence. Root/sudo may be needed for trace capture depending on kernel perf_event_paranoid settings.

• Hardware Performance Counters (PMU) — rr uses CPU performance monitoring unit counters to detect non-determinism (branch count divergence) during replay; understanding PMU virtualization in VMs is essential for deployment
• Ptrace (process tracing) — rr's fundamental mechanism for intercepting and recording syscalls, signals, and memory access; Linux ptrace() API is the backbone of the recording engine
• Deterministic Replay / Time-Travel Debugging — rr's core capability—recording a trace once allows unlimited replays with identical behavior, enabling reverse execution and breakpoint rewinding
• Microarchitecture-specific Performance Monitoring — rr requires Nehalem+ PMC virtualization support; different CPU generations (Zen, Neoverse) have different counter availability; this drives CPU compatibility matrix
• Cap'n Proto Serialization — rr uses Cap'n Proto (12.7K LoC in repo) for efficient binary trace serialization; understanding its schema format is necessary for trace inspection or format evolution
• GDB Remote Protocol Extension — rr extends gdb via Python scripting and custom remote protocol commands (scripts/rr-gdb-script-host.py); replay UI is built on gdb's remote debugging interface
• x86 Instruction Emulation & System Call Interception — rr must intercept and replicate all syscalls deterministically; Assembly code (57K LoC) handles low-level hooks for signal delivery, syscall patching, and instruction-level semantics

• mozilla/grcov — Complements rr by providing code coverage instrumentation; rr traces can be analyzed with grcov to achieve deterministic coverage reports
• mozilla/pernosco — Commercial time-travel debugger UI built atop rr traces; Pernosco sponsors rr development and uses its trace format as the foundation
• torvalds/linux — Core dependency—rr relies on kernel ptrace(), perf_event, and PMU APIs; kernel version constraints (>= 4.7) drive compatibility
• bminor/gdb — Debugger backend—rr embeds and extends gdb for replay inspection; compatible gdb versions are critical for rr's reverse-execution UI
• google/sanitizers — Often used alongside rr to detect memory corruption and race conditions; rr traces can be post-processed with ASan/TSan reports for enhanced debugging

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 AddressSpace memory management

AddressSpace.cc/h are core components for managing process memory in rr, but there's no visible dedicated test suite. Given the critical nature of address space handling in a record/replay debugger, adding unit tests would catch regressions and document expected behavior. This is high-value since memory management bugs directly impact debugging correctness.

• [ ] Create src/AddressSpaceTest.cc with tests for memory mapping operations
• [ ] Add tests for address space cloning, modification, and tear-down scenarios
• [ ] Test edge cases like overlapping mappings, permissions changes, and unmapping
• [ ] Integrate tests into CMakeLists.txt test suite
• [ ] Document test coverage in CONTRIBUTING.md if not already present

Add AutoRemoteSyscalls integration tests

AutoRemoteSyscalls.cc/h handles remote syscall execution during recording, which is fundamental to rr's operation. No dedicated test file is visible in the structure. Integration tests would validate syscall injection and execution without side effects, improving confidence in the replay mechanism.

• [ ] Create src/AutoRemoteSyscallsTest.cc with integration tests
• [ ] Add tests for common syscalls (mmap, mprotect, open, write, etc.)
• [ ] Test error conditions and syscall failure handling
• [ ] Verify syscall return values are correctly captured
• [ ] Add to CMakeLists.txt and document in CONTRIBUTING.md

Create GitHub Actions workflow for static analysis and code quality gates

The repo has build-and-test workflows (.github/workflows/build-and-test*.yml) but lacks a dedicated static analysis pipeline. Adding clang-static-analyzer, AddressSanitizer validation, and format checking (referencing .clang-format config) would catch bugs early. This complements existing CI and provides faster feedback for contributors.

• [ ] Create .github/workflows/static-analysis.yml
• [ ] Add clang-tidy checks referencing .clang-format configuration
• [ ] Add clang-static-analyzer scanning for memory/logic errors
• [ ] Include AddressSanitizer and UndefinedBehaviorSanitizer build validation
• [ ] Configure to run on PRs and report results as check status
• [ ] Document code quality expectations in CONTRIBUTING.md

• Add comprehensive test coverage for scripts/rr-collect-symbols.py—currently no dedicated test file visible in the structure; write unit tests exercising symbol extraction from stripped/unstripped binaries and verify output format matches gdb expectations.
• Document CPU capability detection logic in CMakeLists.txt with inline comments and a new wiki page (contribute to rr-project.org docs) explaining how rr detects Nehalem/Zen/Neoverse support, which flags are checked, and how to verify on new hardware.
• Create Android build validation test in .buildkite/lib/ (using Julia) or GitHub Actions—the android-build.yml workflow exists but integration tests are missing; add a simple ARM64 trace replay test for Android that validates core record/replay on ARM.

The rr debugger codebase shows reasonable security posture for a system-level debugging tool. Primary concerns are: (1) potential unsafe patterns in Python and shell scripts requiring code review, (2) Docker configuration requiring verification for production use, (3) build system security requiring validation of input handling. No hardcoded credentials or obvious injection vulnerabilities are apparent from the file structure alone. The project maintains active CI/CD with GitHub Actions, which is positive. Recommendations focus on process improvements rather than critical fixes: conduct security code review of Python/shell scripts, validate build system input handling, ensure Docker images use security best practices, and verify test data doesn't leak sensitive information.

• Medium · Potential Insecure Deserialization in Python Scripts — release-process/prepare-release.py, release-process/test-system.py, scripts/rr-collect-symbols.py, scripts/zen_workaround.py. The codebase contains multiple Python scripts (prepare-release.py, test-system.py, rr-collect-symbols.py, zen_workaround.py) that could potentially use unsafe deserialization methods. Without examining the actual code, Python scripts handling external data should be reviewed for pickle usage or eval() calls. Fix: Review all Python scripts for unsafe deserialization patterns. Avoid using pickle, eval(), or exec() with untrusted input. Use safe serialization formats like JSON instead.
• Medium · Docker Image Security Configuration — .android/Dockerfile. The .android/Dockerfile exists but the repository structure suggests this is a build artifact directory. Docker images for CI/CD should be reviewed for base image freshness, minimal attack surface, and proper dependency pinning. Fix: Review Dockerfile for: 1) Use of specific base image versions (not 'latest'), 2) Multi-stage builds to minimize image size, 3) Non-root user execution, 4) Regular security scanning with tools like Trivy or Grype
• Low · Shell Scripts in CI/CD Pipeline — scripts/github-actions-build.sh, scripts/github-actions-test.sh, scripts/signal-rr-recording.sh, .buildkite/ directory scripts. Multiple shell scripts are used in the build and test pipelines (.buildkite/lib/.jl, scripts/github-actions-.sh, etc.). Shell scripts can be vulnerable to command injection if they process external inputs improperly. Fix: Review shell scripts for proper input validation and quoting. Use shellcheck tool to identify potential vulnerabilities. Ensure all variables are properly quoted and external inputs are sanitized.
• Low · Missing Security Configuration in Configuration Files — rr.spec, snap/snapcraft.yaml. The rr.spec file is a RPM spec file that could contain security-relevant configurations. Snap configuration (snap/snapcraft.yaml) should enforce security confinement. Fix: 1) Review rr.spec for proper file permissions and ownership. 2) Ensure snapcraft.yaml uses 'strict' confinement mode and properly declares required plugs and slots.
• Low · Potential Code Injection in Build System — CMakeLists.txt, configure. CMakeLists.txt and the configure script are entry points for the build system. These could be vulnerable to injection if they process user input or environment variables without proper validation. Fix: Review build configuration scripts for proper escaping and validation of variables. Ensure no direct evaluation of user-supplied build parameters. Use modern CMake practices with quoted variables.
• Low · Test Data Files May Contain Sensitive Information — release-process/test-data/. The release-process/test-data directory contains test files (HTML, ODT documents). These should be reviewed to ensure they don't contain sensitive information, credentials, or paths that could leak operational details. Fix: Review test data files to ensure they don't contain: 1) Real credentials or API keys, 2) Internal IP addresses or hostnames, 3) User information or PII, 4) Sensitive configuration details

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.