Repository Guide for Coding Agents

July 29, 2026 · View on GitHub

Start here

BTrace is a Java tracing tool: the client compiles and sends a script, the agent instruments the target JVM, and the runtime emits results. The root project is a multi-module Gradle build.

  • btrace-agent — attachable agent, script lifecycle, and bytecode instrumentation/weaving
  • btrace-compiler — script verification and compilation
  • btrace-runtime / btrace-core — script APIs, runtime support, and protocol
  • btrace-client — CLI and attachment client
  • btrace-dist — distribution assembly; integration-tests — end-to-end tests
  • btrace-extensions/* — extension API and implementations

For the developer command reference and code-navigation pointers, see CLAUDE.md. For user and contributor documentation, start at docs/README.md.

Non-negotiable rules

  • Do not commit unless the changes are fully tested or the user explicitly requests a commit.
  • Preserve unrelated working-tree changes.
  • In Java code, import types and use simple names; do not introduce fully qualified type names in source.
  • Main code targets Java 8 and uses the Java 11 toolchain. Follow Spotless/Google Java Format.
  • Unit tests live in src/test/java and use *Test; integration tests live in integration-tests/src/test/java.
  • Changes to user-visible behavior that crosses modules or process boundaries must include end-to-end functional coverage in integration-tests; unit and component tests are required where useful but are not a substitute for exercising the real client, agent, target JVM, and protocol interaction.
  • Confirm that a new test or build gate fails when it should, not only that it passes. Run it against the unfixed code, or against input it must reject, and check the failure is the expected one. A check that cannot fail reports success regardless of what the code does, and reads as coverage while providing none. Where a revert is used to produce the failure, revert only the code under test: reverting too much fails for an unrelated reason and proves nothing about the behavior being asserted.

Build and verification

Run Gradle with a workspace-local cache in restricted environments:

GRADLE_USER_HOME=$(pwd)/.gradle-user ./gradlew :module:test

Do not consume Gradle output directly. Redirect it to a file, filter it to relevant lines, then read that file. Use spotlessCheck for validation and spotlessApply only when formatting changes are intended. Build :btrace-dist:build before integration tests.

If a restricted network environment causes address-selection failures, add:

JAVA_TOOL_OPTIONS="-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false"

Distribution changes

btrace.jar is a masked single-JAR distribution. Classes must be assigned to bootstrap, agent, client, or shared sections deliberately. Any masked-JAR structure change requires:

./gradlew clean :btrace-dist:btraceJar

Read Masked JAR Architecture before modifying its class layout or loader behavior.

Documentation placement

  • User-facing and contributor documentation belongs in docs/; keep docs/README.md current when adding a guide.
  • Plans and session notes belong in internal/plans/ (or internal/superpowers/plans/).
  • Design/requirement specs belong in internal/specs/ (or internal/superpowers/specs/); libretto/muse files belong in internal/libretti/.
  • Never create or write to a singular doc/ directory, or add plans, agent notes, or internal material below docs/.

Reference map