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/opengoofy/hippo4j 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 8w ago
• 36+ active contributors
• Distributed ownership (top contributor 12% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ No test directory detected

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

What it runs against: a local clone of opengoofy/hippo4j — 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 opengoofy/hippo4j | 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 develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 87 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "opengoofy/hippo4j(\\.git)?\\b" \\
  && ok "origin remote is opengoofy/hippo4j" \\
  || miss "origin remote is not opengoofy/hippo4j (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 develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "agent/hippo4j-agent-bootstrap/src/main/java/cn/hippo4j/agent/bootstrap/Hippo4jAgent.java" \\
  && ok "agent/hippo4j-agent-bootstrap/src/main/java/cn/hippo4j/agent/bootstrap/Hippo4jAgent.java" \\
  || miss "missing critical file: agent/hippo4j-agent-bootstrap/src/main/java/cn/hippo4j/agent/bootstrap/Hippo4jAgent.java"
test -f "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java" \\
  && ok "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java" \\
  || miss "missing critical file: agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java"
test -f "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/PluginBootstrap.java" \\
  && ok "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/PluginBootstrap.java" \\
  || miss "missing critical file: agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/PluginBootstrap.java"
test -f "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/AbstractClassEnhancePluginDefine.java" \\
  && ok "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/AbstractClassEnhancePluginDefine.java" \\
  || miss "missing critical file: agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/AbstractClassEnhancePluginDefine.java"
test -f "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/SnifferConfigInitializer.java" \\
  && ok "agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/SnifferConfigInitializer.java" \\
  || miss "missing critical file: agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/SnifferConfigInitializer.java"

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

Hippo4j is a dynamic observable thread pool framework that enables runtime modification of Java thread pool parameters (core/max threads, queue capacity, rejection policies) without code changes, combined with monitoring, alerting, and task context propagation. It solves the critical pain point of thread pool management in high-concurrency systems by providing centralized control, real-time metrics, and intelligent notifications for thread pool degradation. Monorepo structure: agent/hippo4j-agent-bootstrap/ contains the JVM agent entry point (Hippo4jAgent.java as premain class), agent/hippo4j-agent-core/ holds core instrumentation logic (boot service, base64 utilities, plugin configuration). The framework supports two deployment modes: config-center-based (dynamic config sourcing) and server-based (standalone hippo4j-server Docker image). Frontend is a separate Vue SPA consuming REST APIs from the server.

Backend Java engineers and DevOps teams managing microservices at scale who need to dynamically tune thread pools under production load, monitor task execution anomalies, and receive alerts when thread pools approach capacity or trigger rejection policies—without redeploying.

Production-ready with active development. The project has substantial GitHub engagement (visible star/fork counts), comprehensive CI/CD setup (.github/workflows/ci.yml), multi-language support (Java + Vue frontend), and Docker distribution. The monolithic agent architecture and version compatibility claims (SpringBoot 1.5.x → 2.7.5) suggest real-world deployment experience, though claims beyond 2.7.5 are untested.

Moderate risk: The agent-based instrumentation model (bytecode manipulation via ByteBuddy, see hippo4j-agent-core) introduces JVM startup complexity and potential classloader conflicts. Dependency on external configuration centers (supported modes include config-center and standalone server) creates operational complexity. The shading of ByteBuddy in hippo4j-agent-bootstrap/pom.xml suggests past dependency conflicts. Single language monorepo (Java core + Vue admin UI) means frontend changes may lag backend features.

Active development with focus on framework compatibility (Dubbo, Hystrix, RabbitMQ, RocketMQ consumer thread pool integration), container management (Tomcat, Jetty, Undertow), and change audit workflows (role-based approval for parameter changes). CI is running on every push (.github/workflows/ci.yml). The project actively accepts contributors via detailed issue templates (bug_report, feature_request, enhancement_request, unit_test templates in .github/ISSUE_TEMPLATE/).

Clone and build the agent: git clone https://github.com/opengoofy/hippo4j.git && cd hippo4j && mvn clean package -DskipTests. The agent JAR is built in agent/hippo4j-agent-bootstrap/target/hippo4j-threadpool-agent.jar and can be attached via -javaagent:hippo4j-threadpool-agent.jar. For server mode, Docker is available: docker pull hippo4j/hippo4j-server && docker run -p 8080:8080 hippo4j/hippo4j-server.

Daily commands: Agent mode: java -javaagent:./target/hippo4j-threadpool-agent.jar -javaagent.config=./agent/config/agent.config YourApplication. Server mode (Docker): docker run -e SERVER_PORT=8080 -p 8080:8080 hippo4j/hippo4j-server. Development frontend: Navigate to frontend directory (Vue project), npm install && npm run dev (exact dev script depends on Vue version in package.json).

• agent/hippo4j-agent-bootstrap/src/main/java/cn/hippo4j/agent/bootstrap/Hippo4jAgent.java — JVM agent entry point with premain method; every contributor must understand how the agent bootstraps and attaches to the JVM.
• agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java — Core service lifecycle management; foundational for understanding how agent services are initialized and coordinated.
• agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/PluginBootstrap.java — Plugin discovery and loading orchestration; critical for understanding dynamic instrumentation mechanics.
• agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/AbstractClassEnhancePluginDefine.java — Base class for bytecode enhancement plugins; essential abstraction for thread pool instrumentation.
• agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/SnifferConfigInitializer.java — Agent configuration initialization from properties; required for understanding config-driven behavior.
• agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/bytebuddy/CacheableTransformerDecorator.java — ByteBuddy transformer caching layer; key to performance optimization of class instrumentation.

Add a New Thread Pool Instrumentation Plugin

1. Create a new plugin class extending AbstractClassEnhancePluginDefine in agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/ (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/AbstractClassEnhancePluginDefine.java)
2. Define which target classes and methods to enhance by implementing enhanceClass() and getInstanceMethodsInterceptPoints() (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/interceptor/InstanceMethodsInterceptPoint.java)
3. Create an interceptor handler implementing the appropriate intercept method template (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/bootstrap/template/InstanceMethodInterTemplate.java)
4. Register the plugin in agent/agent/config/agent.config with plugin.list property (agent/config/agent.config)
5. Plugin is auto-discovered at runtime by PluginFinder and loaded by DynamicPluginLoader (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/PluginFinder.java)

Add Dynamic Configuration Property

1. Define the configuration key as a constant in Constants.java (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/Constants.java)
2. Load the property in SnifferConfigInitializer.initialize() from system properties or config file (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/SnifferConfigInitializer.java)
3. Create a watcher in dynamic/ folder to handle runtime changes via AgentConfigChangeWatcher pattern (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/dynamic/AgentConfigChangeWatcher.java)
4. Access the configuration through ServiceManager or plugin context during execution (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java)

Extend Agent Boot Services

1. Create a new class implementing BootService interface in agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/BootService.java)
2. Implement boot() for initialization and shutdown() for cleanup with appropriate priority (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/BootService.java)
3. Register the service via ServiceManager.register() typically from Hippo4jAgent or service loader (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java)
4. ServiceManager handles ordering and lifecycle based on priorities and dependencies (agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/boot/ServiceManager.java)

Agent Attachment Timing: The agent must be attached via -javaagent flag at JVM startup (premain phase); dynamic attachment at runtime is not supported and will silently fail without errors. ByteBuddy Shading: Dependency conflicts can occur if your app uses ByteBuddy; the project shades it to shade.package but inspect your classpath. Config Center Dependency: Config-center mode requires ZooKeeper/Nacos/Consul running; server-mode standalone deployment requires the hippo4j-server container. MDC Context Loss: Original issue states context propagation support, but requires explicit ThreadLocal wrapping in task—vanilla ExecutorService.submit() will lose MDC without framework integration. Version Compatibility Claims: README claims SpringBoot 1.5.x–2.7.5 support but higher versions are 'untested'—verify in your environment before production deployment.

• JVM Agent & Bytecode Instrumentation — Hippo4j's core mechanism—attaching via -javaagent and ByteBuddy enables non-invasive thread pool wrapping without code changes; essential to understand premain lifecycle and class transformation
• Thread Pool Rejection Policies & Task Queueing — Core monitoring target in Hippo4j; understanding ThreadPoolExecutor's reject strategies (AbortPolicy, CallerRunsPolicy, etc.) and queue saturation is why Hippo4j alarms on these conditions
• ThreadLocal & Context Propagation — Hippo4j explicitly addresses MDC context loss across thread boundaries; understanding ThreadLocal capture and task wrapping patterns is critical for preserving tracing/logging context in async work
• Dynamic Parameter Hot-Reload — Core feature—changing corePoolSize, maxPoolSize, queue capacity at runtime without restart; requires careful synchronization and AtomicInteger usage in executor implementation
• Plugin Architecture & Boot Service Pattern — Hippo4j's ServiceManager + BootService enables pluggable framework adapters (Dubbo, Hystrix, etc.); understanding service discovery and lifecycle management is key to extending the agent
• Time-Series Metrics & Alerting Thresholds — Hippo4j collects thread pool activity (active threads, queue depth, task latency) and triggers alerts on thresholds; understanding alert strategy design (capacity water-level, rejection rate, latency percentiles) informs operational setup
• Maven Shade Plugin & Dependency Shading — Hippo4j shades ByteBuddy to avoid classpath conflicts; understanding shade configuration, package relocation, and JAR structure is necessary for troubleshooting agent loading issues

• alibaba/transmittable-thread-local — Complementary library for reliable context propagation across thread pools, solves the MDC loss problem that Hippo4j acknowledges
• reactor/reactor-pool — Alternative reactive pool management for async systems; relevant for teams moving from thread pools to reactive models
• prometheus/client_java — Hippo4j integrates Prometheus as a data sink; this is the canonical Java metrics client library used in the integration
• elastic/elasticsearch-java — Hippo4j supports ElasticSearch as a data sink for thread pool metrics storage and historical analysis
• alibaba/Sentinel — Peer traffic management and circuit breaker framework; often deployed alongside Hippo4j for comprehensive resilience control

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 unit tests for agent core plugin system (ByteBuddyCoreClasses, DynamicPluginLoader, AbstractClassEnhancePluginDefine)

The agent module contains critical bytecode enhancement logic in agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/ but appears to lack corresponding unit tests. The plugin system is fundamental to how hippo4j instruments thread pools at runtime. Adding comprehensive unit tests would improve code reliability, catch regressions, and serve as documentation for how the plugin architecture works.

• [ ] Create agent/hippo4j-agent-core/src/test/java/cn/hippo4j/agent/core/plugin/ directory structure
• [ ] Add unit tests for ByteBuddyCoreClasses.java covering class transformation scenarios
• [ ] Add unit tests for DynamicPluginLoader.java covering plugin discovery and loading
• [ ] Add unit tests for AbstractClassEnhancePluginDefine.java covering enhancement context handling
• [ ] Add integration tests for EnhanceContext.java to verify plugin enhancement workflow

Add GitHub Actions workflow for agent module bytecode verification and compatibility testing

The agent module uses ByteBuddy for bytecode manipulation and shades dependencies (net.bytebuddy). The existing .github/workflows/ci.yml lacks specific validation for agent module bytecode compatibility across Java versions (8, 11, 17+). This PR would add a dedicated workflow to verify agent JAR integrity, test bytecode enhancement against different thread pool implementations, and validate shade plugin configuration.

• [ ] Create .github/workflows/agent-verify.yml workflow file
• [ ] Add job to verify hippo4j-threadpool-agent JAR is correctly shaded and signed
• [ ] Add job to test agent bytecode enhancement against Java 8, 11, 17, 21
• [ ] Add job to validate agent bootstrap loader (Hippo4jAgent.java) initialization
• [ ] Add job to test agent against multiple JDK implementations (OpenJDK, Temurin)

Add comprehensive integration tests for agent dynamic configuration watcher (AgentConfigChangeWatcher)

The agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/conf/dynamic/AgentConfigChangeWatcher.java handles runtime configuration changes but appears to lack integration tests. This is critical functionality for the 'dynamic change' feature advertised in the repo description. Integration tests should verify config hot-reload, listener callbacks, and edge cases like invalid configs or rapid changes.

• [ ] Create agent/hippo4j-agent-core/src/test/java/cn/hippo4j/agent/core/conf/dynamic/ directory
• [ ] Add integration tests for AgentConfigChangeWatcher file monitoring and change detection
• [ ] Add tests for config validation and rejection of invalid configurations
• [ ] Add tests for concurrent config updates and listener notification ordering
• [ ] Add tests for config persistence and recovery scenarios

• Add unit tests for agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/base64/Base64.java (Base64 encoding utility for agent configuration)—currently no test file visible, critical for configuration parsing reliability.
• Document the agent.config properties schema with examples for each framework (Dubbo, Hystrix, RabbitMQ, RocketMQ)—file exists at agent/config/agent.config but no inline comments or schema reference found in file list.
• Add Vue component tests for the admin UI (SCSS and TypeScript files visible but no .spec.ts files apparent)—thread pool status dashboard and dynamic parameter change forms need regression test coverage.

• High · Maven Shade Plugin Dependency Bundling — hippo4j-agent-bootstrap/pom.xml. The pom.xml uses maven-shade-plugin version 3.4.1 to bundle dependencies. While this version is relatively recent, the configuration creates an uber JAR that bundles all transitive dependencies including ByteBuddy. This increases the attack surface and makes it difficult to patch vulnerabilities in bundled dependencies independently. The shade plugin should be kept up-to-date and dependency management should be carefully reviewed. Fix: Regularly update maven-shade-plugin to the latest version. Consider implementing a dependency scanning tool (e.g., OWASP Dependency-Check, Snyk) in the CI/CD pipeline. Document all bundled dependencies and their versions.
• High · Java Agent Bytecode Manipulation — agent/hippo4j-agent-bootstrap/src/main/java/cn/hippo4j/agent/bootstrap/Hippo4jAgent.java and plugin infrastructure. The project implements a Java agent (Hippo4jAgent) that uses ByteBuddy for runtime bytecode manipulation of thread pool classes. The file 'agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/InstrumentDebuggingClass.java' and related plugin infrastructure indicate dynamic class instrumentation. This is a privileged operation that could be exploited if agent configuration is not properly validated. Fix: Implement strict validation of agent configuration sources. Use code signing for agent JAR files. Ensure the agent only runs with appropriate JVM security permissions. Add comprehensive logging of instrumentation activities. Validate all plugin definitions before loading.
• Medium · Incomplete POM Configuration — hippo4j-agent-bootstrap/pom.xml. The pom.xml configuration appears to be truncated (ends mid-line with 'shadeSourcesContent>true</shadeSources'). This incomplete configuration could lead to unexpected build behavior or missing security-related build parameters. Fix: Complete and validate the entire pom.xml file. Ensure all XML is properly closed. Add explicit exclusion rules for known vulnerable dependencies. Consider adding <verify> configuration to maven-shade-plugin.
• Medium · Dynamic Plugin Loading Without Validation — agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/DynamicPluginLoader.java and related plugin loading classes. The DynamicPluginLoader.java and PluginFinder.java files indicate dynamic loading of plugins at runtime. Without proper validation and signed plugin verification, this could allow arbitrary code execution through malicious plugin injection. Fix: Implement plugin signature verification using digital signatures. Restrict plugin loading to a whitelist of known plugins. Validate plugin manifests and resources. Log all plugin loading activities with audit trails.
• Medium · Configuration File Security — agent/config/agent.config. The agent.config file location (agent/config/agent.config) is visible in the repository structure. Configuration files may contain sensitive information like server addresses, credentials, or API keys if not properly protected. Fix: Ensure agent.config is never committed with sensitive data. Use environment variables or secure configuration management for sensitive values. Implement file permission restrictions (chmod 600) on configuration files. Document configuration security requirements.
• Medium · ByteBuddy Framework Version Not Specified — hippo4j-agent-core/pom.xml (parent dependency). While the dependency uses maven-shade-plugin to package ByteBuddy, the specific version of ByteBuddy is not visible in the provided pom.xml snippet. ByteBuddy is a complex bytecode manipulation library and should be kept updated for security patches. Fix: Explicitly specify and regularly update ByteBuddy dependency version. Review ByteBuddy security advisories regularly. Pin versions for reproducible builds.
• Low · Potential Information Disclosure in Debugging Classes — agent/hippo4j-agent-core/src/main/java/cn/hippo4j/agent/core/plugin/InstrumentDebuggingClass.java. The presence of InstrumentDebuggingClass.java suggests debugging instrumentation capabilities. If not properly gated by environment checks, this could expose internal system information. Fix: Ensure debugging classes are only active in development/test environments. Implement environment-based feature flags.

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.