Spring Dev Tools Support

[jamesward]

It'd be awesome if the shell (or other persistent runners: MCP, custom web API around an agent, etc) supported auto-reload with Spring Dev Tools.

When I tried this something got out-of-whack. (Note: I will try again and grab logs to share)

[jamesward]

As an example of this not working, see: https://github.com/jamesward/hello-embabel

This exposes an Embabel agent via Spring Web.

When dev tools is on the classpath, the agent is no longer found when using AgentInvocation.

[igordayen]

@jamesward
Could you please elaborate on "When dev tools is on the classpath, the agent is no longer found when using AgentInvocation."

upon restart agent is no longer operational? thank you

[jamesward]

Steps to reproduce:

1. Clone https://github.com/jamesward/hello-embabel
2. Uncomment the spring-boot-devtools dependency
3. Setup AWS credentials
4. Run: ./mvnw spring-boot:run
5. Make a GET request to: http://localhost:8080

This produces the error:

08:58:19.238 [tomcat-handler-0] ERROR [dispatcherServlet] - Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.IllegalStateException: No agent with outputClass class embabelagent.JokeAndRating found.] with root cause
java.lang.IllegalStateException: No agent with outputClass class embabelagent.JokeAndRating found.

If you comment out the spring-boot-devtools dependency and re-start, everything works as expected.

[igordayen]

Thank you, James

[igordayen]

It'd be awesome if the shell (or other persistent runners: MCP, custom web API around an agent, etc) supported auto-reload with Spring Dev Tools.

When I tried this something got out-of-whack. (Note: I will try again and grab logs to share)

Experiment

Experimented with Shell. please refer to code:
https://github.com/igordayen/embabel-dev-research

Summary

Combination of DevTools and Spring Shell works fine, as long as auto-reload gets disabled (see application.properties.

Sharing full problem statement in a separate window.

Would you please consider moving this to discussion if you feel that's is proper approach.

@jamesward please advise.

@johnsonr , @alexheifetz , @poutsma -FYI

[igordayen]

Spring Shell 3.x & Spring Boot DevTools Restart: Technical Analysis

Problem Statement

A Spring Boot application using Spring Shell 3.x enters an interactive CLI mode on startup. When Spring Boot DevTools is enabled with automatic restart, modifying any classpath resource triggers a DevTools restart cycle.

Observed behavior:

Before restart:

• Spring Shell loads normally

• Commands are available (e.g., OA → 29 completions)

After restart:

• Shell prompt remains visible

• Commands disappear (No command found for 'OA')

• TAB completion breaks

• Application becomes partially unresponsive

DevTools logs show restart triggered, but the application does not fully reinitialize

Manual termination (CTRL+C) is required to recover.

Impact: The interactive shell becomes unusable after any DevTools-triggered restart.

Root Cause: Why DevTools Restart Does Not Work

1 Spring Shell 3.x blocks the main thread

• Spring Shell 3.x starts an interactive terminal loop that:

• initializes JLine/Jansi terminal

• builds the command catalog

• enters a blocking read–eval–print loop

• never returns control to the main thread

2. DevTools restart requires the main thread to return

• DevTools restart works by:

• Stopping the old ApplicationContext

• Creating a new restart classloader

• Re-running the application entrypoint (main)

• Expecting the main thread to complete initialization again

But because Spring Shell 3.x never releases the main thread, DevTools cannot:

• reinitialize the shell

• rebuild the command catalog

• rebind the terminal

• reattach input/output streams

3. Classloader split occurs

After restart:

• The shell loop remains in the old classloader

• The commands reload in the new restart classloader

• The shell cannot see the new beans

• Command catalog becomes stale or empty

• This produces the exact failure:

No command found for 'OA'

4 Even full DevTools include/exclude tuning cannot fix this

Even when forcing DevTools to reload:

• Spring Shell core

• Spring Shell terminal subsystem

• JLine

• Jansi

• Project classes

• Custom agent JARs

…the shell loop still never reinitializes because DevTools cannot restart the application while the shell loop is blocking.

Conclusion: Spring Shell 3.x interactive mode is not compatible with DevTools restart.

5. Why Disabling Restart Fixes the Problem

Setting:

spring.devtools.restart.enabled=false

disables only the restart classloader, not DevTools itself.

This avoids:

classloader splits

stale shell loops

broken command catalogs

terminal reinitialization failures

The shell runs once, stays alive, and remains stable.

You still have benefits :

• enhanced logging

• classpath diagnostics

• LiveReload (if enabled)

• remote DevTools support

You lose only the restart feature — which Spring Shell cannot support anyway.

Options to Fix or Work Around the Limitation

Option A — Disable DevTools Restart (Recommended for Spring Shell 3.x)

spring.devtools.restart.enabled=false

Pros:

Stable interactive shell

No classloader issues

No disappearing commands

No terminal corruption

Cons:

No hot reload of Java classes

Option B — Downgrade to Spring Shell 2.x

Spring Shell 2.x:

does not block the main thread

is restart-friendly

reinitializes cleanly after context refresh

supports built-in commands (help, quit, etc.)

Pros:

Full DevTools restart compatibility

Stable interactive shell

No custom engineering required

Cons:

Older API

Different annotation model

Less modern command framework

Option C — Redesign ShellCommand Beans to Make the Shell Restartable

This requires:

running the shell loop in a separate thread

detecting DevTools restarts (ContextClosedEvent)

gracefully shutting down the old shell loop

reinitializing terminal + JLine + Jansi

rebuilding the command catalog

starting a new shell loop bound to the new context

Pros:

Full DevTools restart

Full interactive shell

Modern Spring Shell 3.x API

Cons:

Significant custom engineering

Must manage terminal lifecycle manually

Must handle thread cleanup and rebind I/O

Not supported by Spring Shell out of the box

5. Summary

Option

Interactive Shell

DevTools Restart

Effort

Stability

A. Disable restart

✅ Yes

❌ No

⭐ Easy

✅ Very stable

B. Downgrade to Shell 2.x

✅ Yes

✅ Yes

⭐⭐ Medium

✅ Stable

C. Custom restartable shell loop

✅ Yes

✅ Yes

⭐⭐⭐⭐ High

✅ Stable (with engineering)

6. Final Recommendation

For Spring Shell 3.x interactive applications, the correct and stable configuration is:

spring.devtools.restart.enabled=false

This avoids architectural conflicts between DevTools and the Spring Shell terminal loop, while preserving all other DevTools benefits.

If hot reload is a hard requirement, consider:

downgrading to Spring Shell 2.x, or

implementing a custom restartable shell loop

—but these require deliberate architectural changes.