{
  "markdown": "# MCP Server for rr Reverse Debugging (karellen-rr-mcp)\n\n[![Gitter](https://img.shields.io/gitter/room/karellen/lobby?logo=gitter)](https://gitter.im/karellen/Lobby)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/karellen/karellen-rr-mcp/build.yml?branch=master)](https://github.com/karellen/karellen-rr-mcp/actions/workflows/build.yml)\n[![Coverage Status](https://img.shields.io/coveralls/github/karellen/karellen-rr-mcp/master?logo=coveralls)](https://coveralls.io/r/karellen/karellen-rr-mcp?branch=master)\n\n[![karellen-rr-mcp Version](https://img.shields.io/pypi/v/karellen-rr-mcp?logo=pypi)](https://pypi.org/project/karellen-rr-mcp/)\n[![karellen-rr-mcp Python Versions](https://img.shields.io/pypi/pyversions/karellen-rr-mcp?logo=pypi)](https://pypi.org/project/karellen-rr-mcp/)\n[![karellen-rr-mcp Downloads Per Day](https://img.shields.io/pypi/dd/karellen-rr-mcp?logo=pypi)](https://pypi.org/project/karellen-rr-mcp/)\n[![karellen-rr-mcp Downloads Per Week](https://img.shields.io/pypi/dw/karellen-rr-mcp?logo=pypi)](https://pypi.org/project/karellen-rr-mcp/)\n[![karellen-rr-mcp Downloads Per Month](https://img.shields.io/pypi/dm/karellen-rr-mcp?logo=pypi)](https://pypi.org/project/karellen-rr-mcp/)\n\n## Overview\n\n`karellen-rr-mcp` is an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol)\nserver that enables any MCP-compliant LLM client to use [rr](https://rr-project.org/) for\nreverse debugging. Instead of iteratively adding debug output and rebuilding, the LLM can\nrecord a failing test with rr, then replay it with full forward and reverse debugging via\nGDB/MI, inspecting program state without modifying source code.\n\n## Requirements\n\n- **Linux** on x86-64 (rr only supports Linux; aarch64 is experimental)\n- **[rr](https://rr-project.org/)** installed and on PATH\n- **[GDB](https://www.sourceware.org/gdb/)** installed and on PATH (used by rr for debugging)\n- **Python** >= 3.10\n- **`perf_event_paranoid`** set to `1` to allow recording:\n  ```bash\n  sudo sysctl kernel.perf_event_paranoid=1\n  ```\n\n### Installing rr and GDB\n\n**Via pip** (using [karellen-rr](https://github.com/karellen/karellen-rr)):\n```bash\npip install karellen-rr-mcp[rr]\n```\n\nThis installs rr as a pip package alongside karellen-rr-mcp. GDB must still be installed\nseparately via your system package manager.\n\n**Fedora / RHEL / CentOS:**\n```bash\nsudo dnf install rr gdb\n```\n\n**Ubuntu / Debian:**\n```bash\nsudo apt install rr gdb\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S rr gdb\n```\n\n### Configuring perf_event_paranoid\n\nrr requires access to hardware performance counters. Set `perf_event_paranoid` to `1`:\n\n```bash\nsudo sysctl kernel.perf_event_paranoid=1\n```\n\nTo make this persistent across reboots:\n\n```bash\necho 'kernel.perf_event_paranoid=1' | sudo tee /etc/sysctl.d/50-rr.conf\n```\n\n### Verify the setup\n\n```bash\nrr record /bin/true && echo \"rr is working\"\n```\n\nIf this fails with a permissions error, check `perf_event_paranoid`. If it fails inside\na container or VM, note that rr requires access to CPU performance counters — it does\nnot work in most containers (Docker, Podman) or VMs unless hardware PMU passthrough is\nconfigured.\n\n## Installation\n\n```bash\npip install karellen-rr-mcp\n```\n\nOr with pipx for an isolated environment:\n\n```bash\npipx install karellen-rr-mcp\n```\n\n## Claude Code Integration\n\n### Claude Code plugin (recommended)\n\nThe plugin automatically configures the MCP server and includes:\n\n- **Crash detection hook** that suggests rr when a Bash command exits with a signal\n  (SIGSEGV, SIGABRT, SIGBUS, etc.) or output contains crash/sanitizer signatures\n- **`/karellen-rr-mcp:rr-debug` skill** that walks through the full\n  record-replay-analyze workflow step by step\n- **`rr-investigator` agent** that Claude can spawn to autonomously investigate\n  crashes using rr reverse execution\n\nFrom the [Karellen plugins marketplace](https://github.com/karellen/claude-plugins):\n\n```bash\nclaude plugin marketplace add karellen/claude-plugins\nclaude plugin install karellen-rr-mcp@karellen-plugins\n```\n\nOr from the official Anthropic marketplace (if accepted):\n\n```bash\nclaude plugin install karellen-rr-mcp@claude-plugins-official\n```\n\nOr load directly from a local checkout for testing:\n\n```bash\nclaude --plugin-dir /path/to/karellen-rr-mcp\n```\n\n### Manual MCP server configuration\n\nIf you prefer not to use the plugin, you can configure the MCP server directly.\nThis gives you the MCP tools but not the skill, agent, or crash detection hook.\n\nUsing the CLI:\n\n```bash\nclaude mcp add --transport stdio karellen-rr-mcp -- karellen-rr-mcp\n```\n\nOr manually add to `~/.claude.json` (user scope) or `.mcp.json` in your project root\n(project scope, shared via version control):\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-rr-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"karellen-rr-mcp\"\n    }\n  }\n}\n```\n\nIf installed with pipx:\n\n```bash\nclaude mcp add --transport stdio karellen-rr-mcp -- pipx run karellen-rr-mcp\n```\n\nor manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-rr-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"karellen-rr-mcp\"]\n    }\n  }\n}\n```\n\n### Auto-approve rr tools\n\nBy default Claude Code will prompt for confirmation before each `rr_*` tool call.\nYou can approve individually by selecting \"Yes, and don't ask again\" when prompted.\n\nTo auto-approve all tools upfront, add a permission rule to your user settings\n(`~/.claude/settings.json`):\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__plugin_karellen-rr-mcp_karellen-rr-mcp__*\",\n      \"mcp__karellen-rr-mcp__*\"\n    ]\n  }\n}\n```\n\nThe first rule covers plugin-loaded tools, the second covers manual MCP configuration.\n\nOr for a project-scoped setting, add the same rule to `.claude/settings.json` in your\nproject root (this file can be committed to version control so all team members get it).\n\n## Available Tools\n\n### Session Lifecycle\n| Tool | Description |\n|------|-------------|\n| `rr_record` | Record a command with rr. Returns trace directory path. |\n| `rr_replay_start` | Start replay session (launches rr gdbserver + GDB/MI). |\n| `rr_replay_stop` | Stop current replay session, clean up. |\n| `rr_list_recordings` | List available rr trace recordings. |\n| `rr_ps` | List processes in a trace recording (PID, PPID, exit code, command). |\n| `rr_traceinfo` | Get trace metadata (header info in JSON format). |\n| `rr_rm` | Remove an rr trace recording. |\n| `rr_when` | Get current rr event number (position in trace). |\n\n### Breakpoints\n| Tool | Description |\n|------|-------------|\n| `rr_breakpoint_set` | Set breakpoint at function/file:line/address. |\n| `rr_breakpoint_remove` | Remove a breakpoint. |\n| `rr_breakpoint_list` | List all breakpoints. |\n| `rr_watchpoint_set` | Set hardware watchpoint (write/read/access). |\n\n### Execution Control\n| Tool | Description |\n|------|-------------|\n| `rr_continue` | Continue forward or backward. |\n| `rr_step` | Step into (forward or reverse). |\n| `rr_next` | Step over (forward or reverse). |\n| `rr_finish` | Run to function return (or call site if reverse). |\n| `rr_run_to_event` | Jump to specific rr event number. |\n\n### Thread and Frame Navigation\n| Tool | Description |\n|------|-------------|\n| `rr_thread_list` | List all threads with state and location. |\n| `rr_thread_select` | Switch to a different thread. |\n| `rr_select_frame` | Select a stack frame for inspection (locals/evaluate use that frame). |\n\n### State Inspection\n| Tool | Description |\n|------|-------------|\n| `rr_backtrace` | Get call stack. |\n| `rr_evaluate` | Evaluate C/C++ expression in current context. |\n| `rr_locals` | List local variables with values. |\n| `rr_read_memory` | Read raw memory bytes. |\n| `rr_registers` | Read CPU registers. |\n| `rr_source_lines` | List source code around current position. |\n\n### Checkpoints\n| Tool | Description |\n|------|-------------|\n| `rr_checkpoint_save` | Save checkpoint at current position. |\n| `rr_checkpoint_restore` | Restore to saved checkpoint. |\n\n## Configuration\n\n### Timeouts\n\nAll timeouts are configurable via environment variables (in seconds). Set them in your\nMCP server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"karellen-rr-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"karellen-rr-mcp\",\n      \"env\": {\n        \"RR_MCP_TIMEOUT_FORWARD\": \"300\",\n        \"RR_MCP_TIMEOUT_REVERSE\": \"600\"\n      }\n    }\n  }\n}\n```\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `RR_MCP_TIMEOUT_STARTUP` | 30 | Waiting for rr gdbserver to start listening |\n| `RR_MCP_TIMEOUT_CONNECT` | 60 | GDB connecting to rr (includes symbol loading) |\n| `RR_MCP_TIMEOUT_FORWARD` | 120 | Forward execution (continue, step, next, finish) |\n| `RR_MCP_TIMEOUT_REVERSE` | 300 | Reverse execution |\n| `RR_MCP_TIMEOUT_BREAKPOINT` | 30 | Breakpoint/watchpoint operations |\n| `RR_MCP_TIMEOUT_EVAL` | 30 | State inspection (backtrace, evaluate, locals, etc.) |\n\nFor large binaries (e.g. MariaDB, Firefox), you may need to increase `RR_MCP_TIMEOUT_CONNECT`\n(symbol loading can take 20+ seconds) and `RR_MCP_TIMEOUT_FORWARD` (replaying to a\nbreakpoint deep in execution can take minutes).\n\n## Troubleshooting\n\n### AMD Zen CPUs\n\nrr does not work reliably on AMD Zen CPUs unless the hardware SpecLockMap optimization\nis disabled. When running rr on Zen you may see:\n\n> On Zen CPUs, rr will not work reliably unless you disable the hardware SpecLockMap\n> optimization.\n\n**Workaround:** run the `zen_workaround.py` script from the\n[rr source tree](https://github.com/rr-debugger/rr) as root:\n\n```bash\nsudo python3 scripts/zen_workaround.py\n```\n\nThis fix must be reapplied after each reboot or suspend. To make it persist, you must\nalso stabilize the Speculative Store Bypass (SSB) mitigation by adding one of the\nfollowing kernel command-line parameters:\n\n- `spec_store_bypass_disable=on` — fully enables SSB mitigation (has performance\n  implications)\n- `nospec_store_bypass_disable` — fully disables SSB mitigation (has security\n  implications)\n\nAlternatively, build and load the `zen_workaround.ko` kernel module from the rr source\ntree, which prevents SSB mitigation from resetting the workaround without requiring\nkernel parameters.\n\nSee the [rr Zen wiki page](https://github.com/rr-debugger/rr/wiki/Zen) for full details.\n\n### MSR kernel module not loaded\n\nThe `zen_workaround.py` script accesses CPU model-specific registers via `/dev/cpu/0/msr`,\nwhich requires the `msr` kernel module. On many distributions this module is not loaded\nby default. If the script fails, load it manually:\n\n```bash\nsudo modprobe msr\n```\n\nTo make this persistent across reboots:\n\n```bash\necho 'msr' | sudo tee /etc/modules-load.d/msr.conf\n```\n\n**Note:** on systems with Secure Boot enabled, the `msr` module may fail to load because\nit is not signed. You may need to either disable Secure Boot in your UEFI/BIOS settings,\nor sign the module with your own Machine Owner Key (MOK).\n\n### MADV_GUARD_INSTALL crash on kernel 6.13+ with glibc 2.42+\n\nLinux 6.13 introduced `MADV_GUARD_INSTALL` (madvise advice 102) for lightweight stack\nguard pages. glibc 2.42+ (e.g. Fedora 43) uses this in `pthread_create`. rr 5.9.0\n(the latest release, from February 2025) does not recognize this madvise advice value\nand crashes with:\n\n```\nAssertion `t->regs().syscall_result_signed() == -syscall_state.expect_errno' failed to hold.\nExpected EINVAL for 'madvise' but got result 0 (errno SUCCESS); unknown madvise(102)\n```\n\nThis was fixed in rr git master\n([commit 34ff3a7](https://github.com/rr-debugger/rr/commit/34ff3a700), August 2025)\nbut has not been included in a release yet. **You must build rr from source** to get\nthe fix:\n\n```bash\ngit clone https://github.com/rr-debugger/rr.git\ncd rr\nmkdir build && cd build\ncmake ..\nmake -j$(nproc)\nsudo make install\n```\n\nSee [rr-debugger/rr#4044](https://github.com/rr-debugger/rr/issues/4044) and\n[rr-debugger/rr#3995](https://github.com/rr-debugger/rr/issues/3995) for details.\n\n## License\n\nApache-2.0\n",
  "bytes": 11944,
  "sha": "c2a886474f8dcc12da869a89052627a628bc198aeac43027338a6a06940019a0",
  "repo_slug": "karellen/karellen-rr-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_karellen_karellen_rr_mcp_karellen_rr_mcp_cea569fa/readme"
}