# Hunter for Android Gradle Bytecode Instrumentation

> Hunter is a Java framework for building Android Gradle plugins that transform bytecode with ASM. It targets developers who need reusable instrumentation across application and third-party code, but its documented setup depends on separate plugin READMEs and a Wiki.

**Leaking/Hunter** — A fast, incremental, concurrent framework to develop compile plugin for android project to manipulate bytecode

- Repository: https://github.com/Leaking/Hunter
- Stars: 1,420 · Forks: 188
- Language: Java
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/leaking-hunter

## Hunter's Android Instrumentation Scope

Hunter addresses a narrow Android build problem: modifying bytecode without writing each transformation, Gradle integration, and incremental pipeline connection from scratch. Its users are Android developers and Gradle plugin authors who want to add behavior consistently across an application and code inside third-party dependencies. The README gives monitoring, dependency enhancement, and Android framework enhancement as intended use cases.

The repository is organized around a core module named `hunter-transform` and separate plugin modules for OkHttp, timing, debugging, and log-line transformations. Each area also has a library module and an example directory. That separation indicates that Hunter is a framework for building and packaging instrumentation, not an application library that Android developers add directly to production code.

This distinction matters. Hunter-based tools alter compiled classes during the Android build. They are more appropriate when source-level changes cannot cover every relevant call site, especially when a client may be instantiated inside a dependency whose source is not under the application's control. They are less suitable when a normal dependency injection mechanism, public API change, or source modification would be easier to audit and maintain.

## AGP and AsmClassVisitorFactory Integration

Hunter 1.3.x connects to Android Gradle Plugin through `AndroidComponentsExtension.onVariants` and AGP's `AsmClassVisitorFactory`. Those APIs provide the connection between an Android variant and ASM class visitors. According to the README, Hunter-based plugins inherit AGP's incremental and parallel instrumentation pipeline rather than introducing a separate transformation framework.

The transformation model is bytecode inspection and modification. Hunter uses ASM 9.7 in its 1.3.x line, while Java 17 support allows processing newer class-file features such as records and sealed classes. Constructor instrumentation receives special attention because Java constructors must invoke `super(...)` or `this(...)` before certain statements can be inserted. The README states that the timing probe is now placed after that mandatory call, addressing the constructor instrumentation bug associated with issue `#48`.

This design keeps Hunter close to AGP's compilation model, but it also ties the framework to Android builds. It is not presented as a general-purpose Java bytecode library. Non-Android Gradle projects would gain little from its variant registration and Android-specific pipeline.

## Hunter Compatibility Boundaries for AGP and Java

The documented compatibility boundary changed substantially in version 1.3.0. Hunter 1.3.x supports Android Gradle Plugin 7.4 through 8.7 and later, Gradle 8.0 or later, ASM 9.7, and Java 17. Hunter 1.2.x targets the older Transform API with Android Gradle Plugin 4.x, Gradle 7.x, ASM 7.1, and Java 8.

That older path is unavailable in Hunter 1.3.x. The README says the legacy `Transform` API was removed because AGP 8.0 removed it, and Hunter now uses `AndroidComponentsExtension.onVariants` with `AsmClassVisitorFactory`. A team cannot select Hunter 1.3.x merely because the application compiles. The Android toolchain must meet the documented AGP and Gradle requirements, and the build must use Java 17.

The distinction can make upgrades expensive. Moving from a Hunter 1.2.x setup may require an AGP upgrade rather than only a Hunter dependency update. Likewise, choosing Hunter solely to support ASM processing does not guarantee compatibility with an older build. Version alignment is therefore a first-order adoption check, not a minor packaging concern.

## Hunter Installation and First Plugin Evaluation

The main README directs developers to Maven Central for the current version and to the Wiki for the Developer API. It also links to a separate README for each bundled plugin, which is where configuration examples would need to be checked. The shared version declaration shown in the README is:

```groovy
def hunterVersion = '1.3.1'
```

This assignment sets the version used when the individual plugin configuration is applied. The main README does not show the dependency declaration, plugin ID, repositories block, or Android application configuration.

For a first evaluation, open the relevant plugin README under `docs/` and compare its declared configuration with the target application. Then use the Developer API Wiki to determine how `AsmClassVisitorFactory` is registered and how class matching is scoped. The repository's example directories can identify the intended module structure, but they are examples rather than documented installation steps. This makes Hunter less convenient to trial from the main page alone than a Gradle plugin with a copy-and-paste setup.

## Hunter Plugin Modules and Targeted Transformations

The listed plugins show several ways bytecode changes can target behavior that is otherwise difficult to reach consistently. The OkHttp plugin is described as setting a global interceptor, event listener, or DNS implementation for OkHttp clients, including clients created inside third-party libraries. The timing plugin instruments UI-thread methods and can dump block traces with timing details. The debug plugin prints method parameters, elapsed time, and return values for annotated methods. The LogLine plugin adds line numbers to Logcat entries.

These examples use bytecode manipulation for scope rather than simple code generation. Global OkHttp behavior is useful when clients are created in code the application does not own. UI timing can cover methods selected during compilation. Annotation-driven debugging limits instrumentation to marked entry points, while log-line rewriting applies across generated Logcat statements.

Not every transformation is safe merely because AGP can compile it. Altering constructor placement can violate bytecode verification, and applying a global interceptor or DNS setting changes behavior for every affected client. Plugin authors must define precise class and method filters, account for types and behavior in dependencies, and test transformed output on the supported AGP range. Hunter supplies the framework, but the README does not claim that every arbitrary bytecode rewrite is automatically safe.

## Hunter Licensing, Releases, and Upgrade Cost

The repository metadata does not identify a license, but the README includes the Apache License, Version 2.0 text and links to the Apache license. It states that the libraries and plugins share a version number, with `1.3.1` shown in the README. The repository has no GitHub releases, while Maven Central is the documented publication channel. Teams should therefore verify artifact availability and source-to-artifact versions before standardizing on a version.

The repository is not archived, and its last push was on 2026-04-26. No release history is provided, so upgrade frequency and release cadence cannot be inferred from GitHub releases. The explicit migration from the Transform API to `AndroidComponentsExtension.onVariants` is the clearest documented upgrade cost. Plugin authors may need to adapt code written for AGP's removed Transform API, while application teams may also face Java, Gradle, and AGP changes.

The Apache License text allows use and modification under its stated conditions, including notice and license requirements. This review does not assess legal compliance for a particular distribution or plugin combination.

## Hunter Versus a Direct AGP Instrumentation Plugin

The closest alternative is to implement an Android Gradle plugin directly with `AndroidComponentsExtension.onVariants` and `AsmClassVisitorFactory`. Both approaches use AGP's instrumentation hooks and ASM. The difference is scope: Hunter is a framework intended to reduce repeated implementation work and supply reusable integration patterns, while a direct plugin leaves the application free to keep its instrumentation code in one small module.

A direct AGP plugin can be simpler for a single, narrowly scoped transformation because there is no need to evaluate a shared framework and its bundled plugin ecosystem. It also exposes the complete implementation directly to the build owner. Hunter becomes more relevant when several transformations share version management, packaging, Android variant registration, and bytecode-processing infrastructure.

Another alternative is source-level transformation through Gradle source generation or an established dependency-injection API. Those approaches preserve readable source changes and avoid build-time rewriting, but they generally cannot reach behavior hidden in an uninstrumented third-party dependency. Hunter is therefore most defensible when global bytecode reach matters more than source transparency.

## Conclusion

Hunter is appropriate for Android engineers who need repeated bytecode transformations across application and dependency code and can accept its AGP, Java, and ASM version matrix. It is a poor fit for Java 8 projects, AGP 4.x projects, applications that avoid build-time bytecode modification, or teams that require a complete installation guide in the main README. Before adoption, verify the selected plugin's artifact coordinates and configuration, confirm the current Android Gradle Plugin and Java versions, and inspect how the transformed output affects classes supplied by third-party libraries.

## FAQ

### Which Android Gradle Plugin versions are compatible with Hunter 1.3.x?

The compatibility table lists Android Gradle Plugin 7.4 through 8.7 and later for Hunter 1.3.x. It also requires Gradle 8.0 or later, ASM 9.7, and Java 17.

### Does Hunter still support the legacy Android Transform API?

No. Hunter 1.3.0 removed support for the legacy Transform API, which was also removed from AGP 8.0. The current integration uses `AndroidComponentsExtension.onVariants` and `AsmClassVisitorFactory`.

### Where can I find Hunter installation and plugin configuration instructions?

The main README links to the Developer API Wiki for framework development and to separate plugin READMEs under `docs/` for individual plugins. It does not include complete dependency, plugin ID, or Android application configuration steps.

## Sources

- [Issues](https://github.com/Leaking/Hunter/issues)
- [Leaking/Hunter on GitHub](https://github.com/Leaking/Hunter)
- [README](https://github.com/Leaking/Hunter/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leaking-hunter