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/raphw/byte-buddy 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 all four use cases

• Last commit 2d ago
• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits

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

What it runs against: a local clone of raphw/byte-buddy — 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 raphw/byte-buddy | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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"

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

Byte Buddy is a runtime code generation and manipulation library for Java that creates and modifies Java classes during JVM execution without a compiler. It generates arbitrary bytecode at runtime, enabling dynamic proxy creation, method interception, and class transformation far beyond Java's built-in Proxy utilities. The core capability is manipulating Java class files programmatically and attaching agents to running JVMs for live instrumentation. Multi-module Maven monorepo: byte-buddy-agent/ contains the attach/instrumentation layer with JNA bindings and native C code (Windows DLL in src/main/resources/win32-x86-64/), while the parent byte-buddy-parent pom.xml defines core code generation. Packages nest under net.bytebuddy.agent.* with nullability annotations in separate subpackages.

Java developers building frameworks, APM agents, testing libraries, and runtime instrumentation tools who need to dynamically create or modify classes. Specifically: developers of dependency injection frameworks, mocking libraries (like Mockito), Java agents for monitoring/profiling, and anyone implementing method interception or aspect-oriented programming.

Highly mature and production-ready. The repo shows 14.5MB of Java code, active CI/CD in .github/workflows/main.yml with security scanning, extensive test coverage tracked via Coveralls, and CII Best Practices badge. Version 1.18.9 snapshot indicates active development; the README documents compatibility through Java 25 with backward support to Java 5.

Low risk for a mature project. Single maintainer (raphw) means dependency on one person, but the project has institutional backing (CII Best Practices certified). JNA dependency is marked provided scope, so optional. No obvious red flags in commit frequency or open issues visible in file structure; however, Java bytecode manipulation is inherently complex and version-dependent.

Active snapshot development (1.18.9-SNAPSHOT in pom.xml). GitHub workflows show CodeQL analysis and security scanning enabled. The project tracks Java version compatibility table in README, suggesting ongoing work supporting new Java class file formats (25+ currently supported). Dependabot configured for dependency updates.

git clone https://github.com/raphw/byte-buddy.git
cd byte-buddy
./mvnw clean install

Uses Maven Wrapper (.mvn/wrapper/maven-wrapper.properties), no external setup required beyond Java 8+.

Daily commands: Not a runnable application. Byte Buddy is a library used by other projects. To test locally:

./mvnw test

To build agent JAR:

./mvnw -pl byte-buddy-agent package

Resulting agent JAR in byte-buddy-agent/target/byte-buddy-agent-*.jar can be attached via -javaagent.

• byte-buddy-agent/src/main/java/net/bytebuddy/agent/ByteBuddyAgent.java: Entry point for Java agent; handles premain/agentmain hooks for JVM instrumentation
• byte-buddy-agent/src/main/java/net/bytebuddy/agent/Installer.java: Core agent installation logic; orchestrates attachment to running or startup JVMs
• byte-buddy-agent/src/main/java/net/bytebuddy/agent/Attacher.java: JVM attachment implementation; bridges to com.sun.tools.attach and IBM equivalents
• byte-buddy-agent/src/main/c/attach_hotspot_windows.c: Native Windows JVM attachment; compiled to DLL for platforms without JDK attach API
• byte-buddy-agent/pom.xml: Defines agent packaging, native compiler configuration, and JNA dependency setup
• .github/workflows/main.yml: CI pipeline; shows test execution, coverage, and multi-platform build/test matrix

New bytecode transformation: Add classes under byte-buddy/src/main/java/net/bytebuddy/ mirroring the existing structure; tests in corresponding src/test/ mirror. Agent instrumentation: Modify byte-buddy-agent/src/main/java/net/bytebuddy/agent/*.java (e.g., Attacher.java for attachment logic, ByteBuddyAgent.java for agent entry point). Native code: C modifications in byte-buddy-agent/src/main/c/attach_hotspot_windows.c require recompilation with MinGW; DLLs committed to src/main/resources/win32-x86-64/. Configuration: Maven properties in pom.xml control compiler paths (native.compiler.64) and package lists.

1. JVM Attachment Platform Variance: Agent attachment differs significantly between Sun JVM (com.sun.tools.attach), IBM JVM (com.ibm.tools.attach), and Windows (requires native DLL). Tests must run on target platform. 2) Java Version Class File Compatibility: The codebase hardcodes support for specific Java versions (Java 5–25); modifying bytecode generation requires understanding the exact class file format for that version. README version table is authoritative. 3) Native Compilation Required: attach_hotspot_windows.c must be cross-compiled with MinGW; missing or outdated DLLs in src/main/resources/ will silently fail on Windows. 4) Maven Wrapper Checksums: .mvn/checksums.sha256 validates wrapper integrity; any custom Maven setup must be verified against this.

• Java Bytecode (Class File Format) — Byte Buddy generates and modifies bytecode at runtime; understanding the binary class file format (method descriptors, constant pool, attributes) is essential to debug or extend code generation
• Java Instrumentation API (java.lang.instrument) — The agent module relies on Instrumentation for class transformation hooks at JVM startup/runtime; required for understanding how ByteBuddyAgent.premain() and agentmain() work
• JVM Tool Interface (JVMTI) — The Windows native code in attach_hotspot_windows.c implements JVMTI attach protocol; understanding JVMTI is necessary for porting or debugging platform-specific attachment
• Method Descriptor Syntax — Byte Buddy generates method signatures using JVM descriptor notation (e.g., (Ljava/lang/String;)I); this syntax is central to bytecode generation and interception
• ClassLoader Delegation Model — Byte Buddy dynamically defines generated classes via ClassLoader.defineClass(); understanding loader hierarchy and class visibility is critical for avoiding ClassCastException or NoClassDefFoundError in generated code
• ASM (Abstract Syntax Manipulation) Framework — While not explicitly in dependencies here, Byte Buddy's architecture mirrors ASM patterns for visiting and transforming class structures; understanding visitor pattern bytecode manipulation helps navigate the codebase
• JNA (Java Native Access) — The agent uses JNA to call native C libraries (platform attach mechanisms); understanding JNA bridges Java-to-C interop, critical for the Windows DLL integration and platform detection logic

• cglib/cglib — Alternative code generation library for Java; predates Byte Buddy and uses ASM directly for bytecode manipulation
• eclipse/eclipse.jdt.core — Java compiler framework; Byte Buddy uses similar low-level bytecode patterns for runtime class generation
• mockito/mockito — Major consumer of Byte Buddy; uses it for runtime mock object generation and method interception in tests
• openjdk/jdk — The JDK itself; Byte Buddy depends on Instrumentation API, JVMTI, and class file format specs from this repo
• spring-projects/spring-framework — Heavy user of Byte Buddy for AOP proxies and dynamic bean creation in dependency injection

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 integration tests for OpenJ9 VM attachment in byte-buddy-agent

The repo has VirtualMachineForOpenJ9Test.java stub test file, but given that byte-buddy-agent supports multiple JVM implementations (HotSpot, OpenJ9, IBM), there is likely incomplete test coverage for OpenJ9-specific attachment mechanisms. This is critical since OpenJ9 uses different attach APIs (com.ibm.tools.attach vs com.sun.tools.attach). Adding tests would ensure reliability across JVM vendors and catch regressions early.

• [ ] Examine byte-buddy-agent/src/test/java/net/bytebuddy/agent/VirtualMachineForOpenJ9Test.java to identify gaps in test coverage
• [ ] Review byte-buddy-agent/src/main/java/net/bytebuddy/agent/VirtualMachine.java to understand OpenJ9-specific code paths
• [ ] Add integration tests covering OpenJ9 agent attachment, detachment, and error handling scenarios
• [ ] Verify tests run on OpenJ9 runtime via CI (may require extending .github/workflows/main.yml)

Add Windows native compilation tests and documentation for attach_hotspot_windows.c

The repo contains C source code (byte-buddy-agent/src/main/c/attach_hotspot_windows.c) and pre-compiled DLLs for both x86 and x86-64 architectures, but there appears to be no automated test or CI workflow validating native compilation or binary integrity. This is a security risk and makes maintenance difficult. Adding a build/test workflow would ensure Windows attachment functionality works correctly across releases.

• [ ] Create a GitHub Actions workflow (.github/workflows/native-windows-build.yml) to compile attach_hotspot_windows.c using cross-compiler (${native.compiler.32} and ${native.compiler.64})
• [ ] Add checksum validation tests in byte-buddy-agent/src/test/java/net/bytebuddy/agent/ to verify pre-compiled DLLs match source
• [ ] Document the native compilation process in .github/CONTRIBUTING.md with instructions for Windows DLL rebuilds
• [ ] Add test coverage in VirtualMachineAttachmentTest.java for Windows-specific attachment code paths

Implement missing security policy tests for agent installation in byte-buddy-agent

The ByteBuddyAgent and Installer classes perform sensitive operations (runtime agent attachment, classloader manipulation). While SECURITY.md exists, there are no unit tests validating that the agent respects Java SecurityManager policies or handles permission denials gracefully. This is critical for secure deployments in restricted environments (e.g., application servers, cloud platforms).

• [ ] Review SECURITY.md and byte-buddy-agent/src/main/java/net/bytebuddy/agent/Installer.java for security considerations
• [ ] Create InstallerSecurityTest.java in byte-buddy-agent/src/test/java/net/bytebuddy/agent/ testing SecurityManager scenarios
• [ ] Add tests for permission denial handling (AccessControlException, SecurityException) in attachment flows
• [ ] Extend existing InstallerTest.java and ByteBuddyAgentInstallationTest.java with @SecurityTest annotations and SecurityManager context

• Add test coverage for byte-buddy-agent/src/main/java/net/bytebuddy/agent/VirtualMachine.java. The file exists but no corresponding test file is visible in the listing; this would exercise platform-specific VM attachment logic.
• Document the native C build process in .github/ or README. The .mvn/ config shows MinGW compiler paths (native.compiler.32, native.compiler.64), but there's no visible CI step or guide for contributors building the Windows DLL—add a NATIVE_BUILD.md.
• Add nullability constraint tests for byte-buddy-agent/src/main/java/net/bytebuddy/agent/utility/nullability/. The annotations (@NeverNull, @MaybeNull, etc.) are defined but no test validates that the agent respects them under null inputs.

Byte Buddy demonstrates reasonable security practices with a CII Best Practices badge and automated CI/CD workflows. However, critical areas requiring attention include: (1) JNA native library loading security mechanisms need hardening against DLL injection, (2) Agent instrumentation capabilities require strict authentication/authorization controls, (3) Security policy documentation is incomplete, and (4) Full dependency audit is needed as the pom.xml appears truncated in the provided snippet. The project uses provided scopes appropriately and has security governance in place (GitHub Security Advisories, vulnerability response SLAs), but implementation details need verification. Recommend conducting a full security audit of agent attachment mechanisms and native code loading.

• Medium · JNA Dependency with Potential Native Code Risks — byte-buddy-agent/pom.xml, byte-buddy-agent/src/main/resources/win32-x86*/attach_hotspot_windows.dll. The project includes JNA (Java Native Access) as a provided dependency for VM attachment functionality. JNA enables calling native code, which can introduce security risks if not properly validated. The project loads native DLLs (attach_hotspot_windows.dll) from resources, which could be vulnerable to DLL injection or manipulation attacks if the loading mechanism is not secure. Fix: Ensure native library loading validates signatures and checksums of DLL files. Implement secure loading mechanisms that prevent DLL injection. Consider using SecurityManager policies to restrict native library access. Regularly audit JNA usage for proper error handling.
• Medium · Agent Instrumentation Security Controls — byte-buddy-agent/src/main/java/net/bytebuddy/agent/. Byte Buddy is a runtime code generation tool that can instrument JVM classes. The agent (net.bytebuddy.agent.Installer) has significant capabilities to modify running code. If authentication/authorization controls are insufficient, an attacker could potentially attach the agent to modify application behavior, load malicious bytecode, or bypass security restrictions. Fix: Implement strict authentication/authorization for agent attachment. Use SecurityManager policies to restrict who can attach agents. Document security implications clearly. Require explicit user consent before agent attachment. Consider implementing audit logging for all agent operations.
• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file is incomplete (text cuts off mid-sentence at 'Bypassing int'). This incomplete documentation may leave security expectations unclear and could indicate inadequate security governance documentation. Fix: Complete the security policy documentation with all severity classifications, response procedures, and disclosure policies. Ensure comprehensive coverage of Critical, High, Medium, and Low severity issues.
• Low · Dependency Scope Not Explicitly Controlled — byte-buddy-agent/pom.xml. JNA dependencies are marked as 'provided' scope, which is appropriate. However, the pom.xml appears incomplete in the provided snippet, and transitive dependency management is not fully visible. Fix: Explicitly define dependency exclusions and version locks for all transitive dependencies. Use Maven Dependency Plugin to audit the full dependency tree. Consider implementing SBOM (Software Bill of Materials) generation for supply chain transparency.
• Low · Test Dependencies Not Fully Documented — byte-buddy-agent/pom.xml. The provided pom.xml snippet is truncated at the junit dependency declaration, making it impossible to fully audit test dependencies which may introduce vulnerabilities. Fix: Review complete pom.xml files to ensure all test dependencies are necessary and kept up to date. Exclude test dependencies from production builds. Use dependabot.yml (which appears configured) to monitor dependency 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.