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/deivid-rodriguez/byebug 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.

GO — Healthy across the board

• Last commit 1w ago
• 14 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• BSD-2-Clause licensed
• CI configured
• Tests present

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

What it runs against: a local clone of deivid-rodriguez/byebug — 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 deivid-rodriguez/byebug | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | 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 ≤ 38 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause 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 "lib/byebug.rb" \\
  && ok "lib/byebug.rb" \\
  || miss "missing critical file: lib/byebug.rb"
test -f "ext/byebug/byebug.c" \\
  && ok "ext/byebug/byebug.c" \\
  || miss "missing critical file: ext/byebug/byebug.c"
test -f "lib/byebug/command.rb" \\
  && ok "lib/byebug/command.rb" \\
  || miss "missing critical file: lib/byebug/command.rb"
test -f "ext/byebug/context.c" \\
  && ok "ext/byebug/context.c" \\
  || miss "missing critical file: ext/byebug/context.c"
test -f "lib/byebug/attacher.rb" \\
  && ok "lib/byebug/attacher.rb" \\
  || miss "missing critical file: lib/byebug/attacher.rb"

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

Byebug is a production-grade Ruby debugger built as a C extension that leverages TracePoint API for execution control and Debug Inspector API for call stack navigation. It provides stepping, breakpoints, REPL evaluation, and variable tracking without depending on Ruby's internal sources, making it fast and reliable for debugging Ruby programs at runtime. Hybrid Ruby/C architecture: exe/byebug is the command-line entry point, lib/byebug/ contains the Ruby API layer (attacher.rb, breakpoint.rb, command.rb), and ext/byebug/ holds the C extension (byebug.c, context.c, breakpoint.c, threads.c, locker.c) that interfaces with Ruby's TracePoint and Debug Inspector APIs. Configuration via .rubocop.yml and .clang-format reflects both Ruby and C code standards.

Ruby developers (MRI 3.3.0+) who need to debug their applications—particularly Rails developers who add byebug to their code for interactive debugging sessions, and users running Ruby scripts from the command line with byebug myscript.rb to pause and inspect execution.

Production-ready and actively maintained. The project has full CI/CD across Ubuntu, Windows, Fedora via GitHub Actions (build.yml, windows.yml, ubuntu.yml, fedora.yml), a comprehensive test suite, and a CHANGELOG tracking releases. Requires MRI 3.3.0+ and is listed as a Tidelift enterprise package, indicating stability and commercial backing.

Low risk for a mature debugger. Single primary maintainer (deivid-rodriguez) is a potential concern for long-term maintenance, but the gem is well-established with enterprise support. C extension dependency (ext/byebug/) requires compilation, which could cause issues on unusual platforms. No obvious dependency bloat visible—core logic is C-based to minimize overhead.

Active maintenance with recent GitHub Actions workflows (build.yml, daily.yml) ensuring CI on multiple Ruby versions and platforms. Dependabot integration (dependabot.yml) keeps dependencies current. Contributions likely flow through standard pull request process documented in CONTRIBUTING.md.

git clone https://github.com/deivid-rodriguez/byebug.git
cd byebug
bundle install
bundle exec rake

The Gemfile and byebug.gemspec define dependencies; bin/setup.sh provides additional setup. Rakefile coordinates builds, including C extension compilation via ext/byebug/extconf.rb.

Daily commands:

bundle exec byebug path/to/script.rb

Or embed in Ruby code: require 'byebug'; byebug to start REPL. Development: bundle exec rake runs test suite; bin/setup.sh prepares environment for C extension compilation.

• lib/byebug.rb — Main entry point that initializes the debugger, sets up TracePoint hooks, and exposes the public API every contributor must understand.
• ext/byebug/byebug.c — Core C extension implementing the low-level debugger engine, execution control, and context management that all debugging features depend on.
• lib/byebug/command.rb — Abstract base class for all debugger commands; understanding this is essential for adding new commands or modifying existing ones.
• ext/byebug/context.c — C extension managing call stack context, frame navigation, and variable inspection—critical for step/frame/variable commands.
• lib/byebug/attacher.rb — Handles dynamic attachment to running processes and breakpoint initialization; key for understanding how byebug integrates with user code.
• lib/byebug/breakpoint.rb — Core breakpoint abstraction managing creation, conditions, and hit tracking that drives the debugging pause mechanism.
• exe/byebug — CLI entry point script that bootstraps the debugger and hands off to the interactive console.

Add a new debugger command

1. Create a new command class in lib/byebug/commands/ inheriting from Command (lib/byebug/commands/my_command.rb)
2. Implement execute(args) method with your command logic and help/description helpers (lib/byebug/commands/my_command.rb)
3. Register the command by adding it to lib/byebug/commands.rb load list (lib/byebug/commands.rb)
4. Add tests in test/commands/my_command_test.rb following existing test patterns (test/commands/my_command_test.rb)
5. Update GUIDE.md with command description and usage examples (GUIDE.md)

Add a new info subcommand (e.g., info my_feature)

1. Create a new class in lib/byebug/commands/info/ inheriting from Subcommand (lib/byebug/commands/info/my_feature.rb)
2. Implement the execute method to format and print debug information (lib/byebug/commands/info/my_feature.rb)
3. Register the subcommand in lib/byebug/commands/info.rb by adding to SUBCOMMANDS constant (lib/byebug/commands/info.rb)
4. Add tests following the pattern in test/commands/info/ directory (test/commands/info/my_feature_test.rb)

Modify core debugging behavior (C extension)

1. Edit the relevant C file (byebug.c for main loop, context.c for stack, breakpoint.c for breakpoints) (ext/byebug/byebug.c)
2. Recompile the extension using bundle exec rake compile (Rakefile)
3. Run integration tests with bundle exec rake test to verify behavior (Rakefile)
4. Update ext/byebug/byebug.h if adding public interface changes (ext/byebug/byebug.h)

Add support for a new variable inspection type

1. Create subcommand in lib/byebug/commands/var/ (e.g., var/my_vars.rb) (lib/byebug/commands/var/my_vars.rb)
2. Implement variable collection and formatting logic using context API from C extension (lib/byebug/commands/var/my_vars.rb)
3. Register in lib/byebug/commands/var.rb SUBCOMMANDS (lib/byebug/commands/var.rb)
4. Add integration tests in test/commands/var/my_vars_test.rb (test/commands/var/my_vars_test.rb)

• C extension (TracePoint + Debug Inspector APIs) — Provides low-overhead execution control and call stack introspection without patching Ruby internals; fast because compiled to native code.
• Ruby command abstraction (lib/byebug/command.rb) — Enables modular, extensible command system where contributors can add new commands without touching core engine; clear separation of concerns.
• Breakpoint abstraction layer (lib/byebug/breakpoint.rb wraps C) — Provides idiomatic Ruby interface to low-level C breakpoint storage; allows dynamic creation and manipulation from user code.
• Thread-safe locker (ext/byebug/locker.c) — Enables multi-threaded debugging without race conditions; critical for production debugging use cases.

• C extension instead of pure Ruby implementation

  • Why: Performance and reliability for real-world debugging; TracePoint + Debug Inspector APIs require low-level integration.
  • Consequence: Adds C build complexity and platform-specific maintenance; requires compilation per Ruby version and platform.

• Command-based REPL instead of graphical UI

  • Why: Works in terminal/SSH environments; simpler to maintain and integrate with scripts and editors.
  • Consequence: Less discoverable for new users; requires learning command syntax (mitigated by help system).

• Breakpoint conditions evaluated at hit-time (C extension) instead of pre-filtering

  • Why: Allows dynamic condition logic and inspection of runtime state
  • Consequence: undefined

C extension must compile: extconf.rb handles this, but requires build tools (gcc/clang, Ruby headers). Platform-specific issues possible on Windows (workflows suggest ongoing work here). TracePoint overhead: Debugging incurs performance cost proportional to traced code; not suitable for production profiling. MRI 3.3.0+ only: No support for JRuby, TruffleRuby, or older Ruby versions—version check is hard requirement. Thread safety: locker.c manages mutex locks; incorrect usage could deadlock. Debug Inspector API stability: Depends on Ruby internals that may shift; vendored extensions (ext/) tightly coupled.

• TracePoint API — Core mechanism byebug uses to intercept Ruby code execution without modifying interpreter internals; understanding TracePoint events (line, call, return) is essential for understanding how byebug pauses execution
• Debug Inspector API — Allows byebug to inspect call stack frames and local variables at runtime; critical for backtrace and variable display features
• C Extension (Ruby C API) — Byebug's performance comes from C code calling Ruby C API directly; understanding rb_funcall, rb_define_method, and VALUE types is necessary for modifying ext/byebug/ files
• Mutex & Thread Synchronization — locker.c implements thread-safe debugging across multiple concurrent threads; incorrect locking could cause race conditions or deadlocks in multi-threaded Ruby apps
• REPL (Read-Eval-Print Loop) — Byebug provides basic REPL at breakpoints for evaluating Ruby expressions; understanding command parsing (command.rb, command_list.rb) is key to extending REPL features
• Breakpoint & Conditional Logic — lib/byebug/breakpoint.rb and ext/byebug/breakpoint.c implement breakpoint storage and conditional evaluation; understanding this is necessary for adding new break conditions or debugging breakpoint issues
• Native Extension Compilation (extconf.rb) — byebug must compile C code for the target platform; understanding extconf.rb and Rake's native build task is necessary for cross-platform support and troubleshooting compilation failures

• ruby/debug — Official Ruby stdlib debugger (Ruby 3.1+); modern alternative to byebug with TAP protocol support
• pry/pry — Interactive Ruby REPL often paired with byebug for evaluation; byebug README mentions pry does better REPL
• presidentbeef/brakeman — Static security scanner for Rails; often used alongside byebug for comprehensive Ruby application debugging/analysis
• ruby-debug/ruby-debug19 — Predecessor to byebug (pre-MRI 2.0); historical context for how byebug improved over previous generation
• rails/rails — Primary use case for byebug; Rails developers embed byebug in controllers and models for development 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 test coverage for lib/byebug/commands/ subcommands

The repo has multiple command implementations (break.rb, catch.rb, condition.rb, etc.) and nested subcommands (disable/breakpoints.rb, enable/display.rb) but there's no visible test directory structure mapping to these commands. Contributors can add unit tests for each command module to ensure proper argument parsing, validation, and execution logic - critical for a debugger where commands must be reliable.

• [ ] Create test/commands/ directory structure mirroring lib/byebug/commands/
• [ ] Add test_break.rb for lib/byebug/commands/break.rb with tests for breakpoint creation and validation
• [ ] Add test_condition.rb for lib/byebug/commands/condition.rb testing conditional breakpoint logic
• [ ] Add tests for nested subcommands like test/commands/disable/test_breakpoints.rb
• [ ] Ensure tests cover edge cases like invalid line numbers, syntax errors in conditions, and state validation

Implement Windows-specific CI workflow enhancements in .github/workflows/windows.yml

There's a windows.yml workflow file but given byebug's C extension nature (ext/byebug/*.c), Windows builds have unique challenges with compiler toolchains, Ruby DevKit, and extension compilation. Contributors can enhance the Windows CI to properly test extension compilation, add MSVC compiler validation, and test actual debugging functionality on Windows.

• [ ] Review current .github/workflows/windows.yml for extension compilation steps
• [ ] Add explicit Ruby DevKit setup and verification for C extension compilation
• [ ] Add test step that validates ext/byebug/extconf.rb generates correct Makefile for MSVC
• [ ] Add integration test running actual byebug commands on Windows to verify extension functionality
• [ ] Document Windows-specific build requirements in CONTRIBUTING.md if missing

Add integration tests for lib/byebug/attacher.rb and real debugging workflows

The attacher.rb module appears to handle attaching the debugger to running processes, which is a critical feature. There's no visible integration test directory demonstrating real debugging scenarios (stepping through code, hitting breakpoints, inspecting variables). Contributors can create realistic test scripts that exercise the full debugging workflow.

• [ ] Create test/integration/ directory for end-to-end debugging scenarios
• [ ] Write test_basic_debugging.rb that starts a debugger session and validates stepping, breakpoints, and variable inspection
• [ ] Write test_attacher.rb that validates attaching to a running Ruby process using lib/byebug/attacher.rb
• [ ] Add test_command_execution.rb that validates the command execution pipeline with actual debugging commands
• [ ] Ensure tests validate output formats and state transitions match documented behavior in GUIDE.md

• Add RSpec matchers or test helpers for byebug integration testing in lib/byebug/testing/ (currently no test utilities visible in file list; users of byebug in test suites would benefit)
• Document C extension troubleshooting in GUIDE.md: add section on common compilation failures on Windows/ARM/Alpine and their solutions (workflows test these platforms but docs are sparse)
• Implement help <command> subcommand lookup in lib/byebug/command.rb to show detailed help per command (currently no per-command help mechanism visible; improves UX for CLI users)

Byebug is a debugging tool with a moderate security posture. The main concerns are: (1) C extension code which increases attack surface and requires careful memory safety review, (2) Dynamic code execution capabilities that could be exploited if input validation is insufficient, (3) Breakpoint conditions allowing arbitrary Ruby evaluation, and (4) Potential information disclosure through debug output. The tool is generally intended for development use rather than production, which mitigates some risks. No obvious hardcoded secrets or dangerous dependencies were detected in the available file structure. Security improvements should focus on input validation for all command parsing, restricting dangerous operations, and conducting security-focused code review of the C extensions.

• Medium · Native C Extension Attack Surface — ext/byebug/*.c files. The codebase includes C extensions (ext/byebug/byebug.c, context.c, locker.c, threads.c, breakpoint.c) which significantly increase the attack surface. C code is vulnerable to buffer overflows, memory corruption, use-after-free, and other memory safety issues. The extension interfaces with Ruby's internal APIs which may change between versions. Fix: Ensure all C code undergoes rigorous security review and fuzzing. Implement bounds checking, use safe string handling functions, and keep Ruby version compatibility testing current. Consider AddressSanitizer and static analysis tools for C code.
• Medium · Dynamic Command Execution via Debug Commands — lib/byebug/commands/irb.rb, lib/byebug/commands/pry.rb, lib/byebug/commands/debug.rb. The commands structure (lib/byebug/commands/) implements a debugger with various commands including 'irb', 'pry', 'debug', and 'eval'. These commands execute arbitrary code in the debugged context, which could be exploited if byebug is exposed to untrusted input or if breakpoint conditions are attacker-controlled. Fix: Implement strict input validation and sanitization for all debug commands. Restrict command execution to trusted users only. Document security implications clearly. Consider disabling dangerous commands by default.
• Medium · Breakpoint Condition Injection — lib/byebug/breakpoint.rb, lib/byebug/commands/condition.rb. The breakpoint.rb and condition.rb files allow setting conditions on breakpoints. If these conditions are derived from untrusted input, they could allow arbitrary code execution since conditions are evaluated as Ruby expressions. Fix: Validate and sanitize all breakpoint conditions. Implement an allowlist of safe condition patterns. Avoid eval() for condition evaluation if possible. Log all breakpoint modifications.
• Low · Information Disclosure via Debug Output — lib/byebug/commands/info/ directory and general output handling. Debugger output may inadvertently expose sensitive information including file paths, variable values, memory addresses, and stack traces to users who can access the debugger session. Fix: Implement output filtering to redact sensitive patterns (API keys, passwords, SSNs, etc.). Document what information is exposed through debug output. Consider adding a privacy mode.
• Low · Missing Input Validation in Command Parsing — lib/byebug/command_list.rb, lib/byebug/command.rb. The command_list.rb and command.rb files parse user input for debug commands. Insufficient validation could lead to unexpected behavior or exploitation. Fix: Implement strict input validation and type checking for all command arguments. Use regex patterns or parsers to validate expected input formats. Reject unexpectedly formatted commands.
• Low · Potential Path Traversal in File Operations — lib/byebug/commands/edit.rb, lib/byebug/commands/save.rb. Commands like 'edit' and 'save' (lib/byebug/commands/edit.rb, lib/byebug/commands/save.rb) may perform file operations. Without proper path validation, these could be vulnerable to path traversal attacks. Fix: Implement strict path validation using File.expand_path and ensure all paths are within allowed directories. Use Ruby's Pathname class for safe path handling. Reject absolute paths or paths containing '..'.

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.