# HotswapAgent: runtime class redefinition for Java, and what it will not do

> HotswapAgent replaces the edit, restart, wait loop in Java development with runtime class and resource redefinition. It is a JVM agent plus a plugin system for Spring, Hibernate, Tomcat and others, and it depends on an enhanced JVM to work at all.

**HotswapProjects/HotswapAgent** — Java unlimited redefinition of classes at runtime.

- Repository: https://github.com/HotswapProjects/HotswapAgent
- Stars: 2,617 · Forks: 520
- Language: Java
- License: GPL-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/hotswapprojects-hotswapagent

## The restart loop HotswapAgent was built to remove

Standard Java hotswap in a debugger only lets you change a method body. Add a field, rename a method, or introduce a new class and the JVM refuses the redefinition, so the developer restarts the application and waits for the framework to come up again. HotswapAgent exists to remove that wait. The README describes the primary goal as eliminating the traditional "change code -> restart and wait... -> check" cycle, and it frames the result as real-time development inside a running application, including in restricted environments such as Docker containers.

The audience is narrow and specific. It is Java developers working on long-starting applications: Spring contexts, Hibernate sessions, servlet containers. If your application starts in two seconds, this tool buys you very little. If it starts in ninety seconds and you restart it forty times a day, the arithmetic is obvious. The project is not a production deployment tool, although the README notes that the autoHotswap property allows reloading changed classes after compilation even on a production system without a restart.

## The agent, the enhanced JVM, and the plugin registry

Two pieces have to be in place. The first is an enhanced JVM that permits class redefinition beyond method bodies. The README points to JetBrains Runtime builds for Java 17, 21 and 25, TravaJDK for Java 11, and jdk8-dcevm for Java 8. The second is the agent itself, a jar loaded into the JVM.

The agent's own description of what it can do is precise: change a method body, add or rename a method, add or rename a field. The only unsupported operation it names is changing the superclass. That single sentence is the most important line in the README, because it defines the boundary of the tool.

On top of the redefinition engine sits a plugin system. The README's reasoning is that each framework needs its own reloading mechanism to stay consistent after a class is redefined, giving the example of a Hibernate configuration reload after a new entity class is introduced. Plugins are discovered at startup, and the log line the README shows lists HotswapperPlugin, AnonymousClassPatchPlugin, HibernatePlugin, SpringPlugin, JettyPlugin, TomcatPlugin, ZkPlugin and LogbackPlugin. A Spring plugin initialization message reports the Spring core version it bound to.

Discovery is filesystem-based. The README states that all local classes and resources known to the running application are automatically discovered and watched, with the qualification that this covers files on the local filesystem and not files inside a JAR. That is why the extraClasspath property exists: to watch a directory for classes that would otherwise live inside a dependency jar.

## Installing HotswapAgent on Java 17, 21 or 25

The README gives different paths per Java version. For Java 17, 21 and 25 it says to download a JetBrains Runtime build, then copy hotswap-agent.jar into the lib/hotswap folder of that runtime. The filename matters: the README says the file in lib/hotswap must be named hotswap-agent.jar without any version numbers. For Java 11 it points at TravaJDK, which ships with an integrated HotswapAgent. For Java 8 it pairs jdk8-dcevm with a separately downloaded agent jar.

The agent is disabled by default from dcevm-11.0.9 onward, so you must pick a mode with a JVM option. The README lists three:

```bash
-XX:HotswapAgent=fatjar
-XX:HotswapAgent=core
-XX:HotswapAgent=external
```

fatjar loads all plugins and may slightly slow down application startup. core loads only the core JVM plugins, which the README says is faster because there is less scanning and class copying, but you then have to declare the plugins you want as Maven dependencies in your pom.xml. external tells the JVM to expect an agent jar you supply yourself.

For a Java 17 or 21 application the README's launch line combines the enhanced redefinition flag with the fatjar mode:

```bash
-XX:+AllowEnhancedClassRedefinition -XX:HotswapAgent=fatjar
```

Java 11 uses only the HotswapAgent flag, and Java 8 uses the older form:

```bash
-XXaltjvm=dcevm -javaagent:hotswap-agent.jar
```

Start the application in debug mode and read the log. A correct startup prints a HotswapAgent banner followed by a Discovered plugins line listing the plugins found, and later a per-framework initialization message. If your framework is absent from that list, its plugin was not loaded, and redefinition of that framework's state will not behave the way you expect. To check redefinition, the README's instruction is to save a changed resource or use the IDE's HotSwap feature.

For IntelliJ users the README points at a separate plugin, HotSwapHelper, which it says simplifies setup of both the agent and the enhanced JVM.

## The superclass wall and the plugin configuration tax

Changing a superclass is not supported. That is the project's own statement, and it is a hard boundary rather than a rough edge. Any refactoring that inserts an intermediate class, swaps an interface implementation, or moves a method up the hierarchy will force a restart. The same is true for changes the enhanced redefinition does not cover, and the README does not enumerate them beyond the superclass case.

The second cost is configuration. The core mode is faster precisely because it does less, and the price is that plugins become explicit Maven dependencies. The README is blunt about the consequence of the project's breadth: it describes the project as very complex due to the number of supported frameworks and versions, and states that community contribution is mandatory to keep it alive. That is a maintenance signal worth reading literally. Compatibility is a matrix of framework version against plugin, and the README's own contribution suggestions (write a plugin, write an integration test, improve documentation) tell you where the gaps tend to be.

The third limitation is the filesystem rule. Classes and resources inside JAR files are not watched. If your build produces an exploded directory, you are fine; if your workflow depends on repackaged fat jars, you will need extraClasspath or a different approach.

## HotswapAgent against JRebel and against plain debugger hotswap

The obvious comparison is JRebel, which is the commercial product in this space, and the difference is not only price. JRebel is a single vendor's tool with a support contract and a licensing model; HotswapAgent is GPL-2.0 and depends on community plugins per framework. The practical difference shows up when your stack is unusual: with a commercial tool you file a ticket, with HotswapAgent you write the plugin, and the README explicitly invites that by noting a custom plugin can live inside your application.

The other comparison is the free option you already have. A debugger's built-in hotswap needs no extra JVM, no agent jar and no plugin discovery, but it stops at method bodies. HotswapAgent requires you to run an enhanced JVM, which is a real constraint if your team standardises on a vendor JDK build that does not offer one. If your edits are almost always inside existing method bodies, the built-in hotswap is the smaller tool that does the job, and adding an agent plus a non-standard JVM is overhead you would not recover.

## Licence and the cost of keeping it current

HotswapAgent is GPL-2.0. The README links to the GPL v2 text and the Maven badge points at org.hotswapagent:hotswap-agent-core. For most teams the agent is a development-time tool that is not distributed with the application, but the licence question is worth raising with whoever handles compliance before you embed it in a build, and the README's mention that a custom plugin can be part of your application is exactly the case where the answer may differ. This is not legal advice; read the licence text.

Upgrade cost is driven by the JVM, not by the agent alone. Moving from Java 11 to 17 means moving from TravaJDK to a JetBrains Runtime build, and the mode flags change accordingly. The README's own version history shows the pattern: 2.0.3 in January 2026, a 2.0.4-SNAPSHOT line in February 2026, and the repository's last push on 2026-08-26. The release notes are the place to check which framework versions a plugin build was tested against, because that is where the compatibility matrix actually lives.

## Conclusion

Adopt HotswapAgent if you develop a Spring, Hibernate, Tomcat or Jetty application on Java 8, 11, 17, 21 or 25 and you control the JVM launch options, because the payoff is not restarting for every method body change. Do not adopt it if you cannot swap in an enhanced JVM, if your changes routinely touch superclass hierarchies, or if you need a support contract, since the README says community contribution is what keeps the project alive. Before committing, verify three things on your own machine: that your JDK build actually supports -XX:HotswapAgent, that your framework appears in the Discovered plugins log line, and that your build tool's output directory matches what the agent watches. The superclass restriction is the boundary to test first, because it is the one operation the project states it does not support.

## FAQ

### What does HotswapAgent actually do?

It is a JVM agent that performs unlimited runtime class and resource redefinition in a running Java application, so you can change a method body or add a method or field without restarting. It also ships plugins that reload framework state, such as a Hibernate configuration after a new entity class appears.

### Which Java versions does HotswapAgent support?

The README gives separate instructions for Java 8 with jdk8-dcevm, Java 11 with TravaJDK, and Java 17, 21 and 25 with JetBrains Runtime builds. On 17, 21 and 25 you copy hotswap-agent.jar into the runtime's lib/hotswap folder and the file must not carry a version number in its name.

### How do I enable HotswapAgent when it is disabled by default?

From dcevm-11.0.9 the agent is disabled by default, so you select a mode with a JVM option: -XX:HotswapAgent=fatjar, -XX:HotswapAgent=core or -XX:HotswapAgent=external. The core mode loads only core JVM plugins and requires you to add other plugins as Maven dependencies in pom.xml.

### What can HotswapAgent not change?

Changing the superclass is the one operation the README names as unsupported. Everything else it lists, such as changing a method body or adding and renaming methods and fields, is covered.

## Sources

- [HotswapProjects/HotswapAgent on GitHub](https://github.com/HotswapProjects/HotswapAgent)
- [Issues](https://github.com/HotswapProjects/HotswapAgent/issues)
- [License: GPL-2.0](https://github.com/HotswapProjects/HotswapAgent/blob/master/LICENSE)
- [README](https://github.com/HotswapProjects/HotswapAgent/blob/master/README.md)
- [Releases](https://github.com/HotswapProjects/HotswapAgent/releases)

---

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