Spring AI Agent Utils: Claude Code's Toolbox Rebuilt as Spring AI Tools
A Spring AI library that brings Claude Code-inspired tools and agent skills to your AI applications.
At a glance
- What is it?
- A Java library that reimplements Claude Code's file, shell, search, memory and subagent capabilities as Spring AI tools. Useful if you are building an agent inside a Spring application and want the tool layer already written, less useful if you need stability, since the API is still moving at v0.12.0.
- Who is it for?
- Adopt it if you are already on Spring AI, need file, shell, grep, glob, web and task tools wired into a ChatClient, and can tolerate a 0.x API. Do not adopt it if you need a stable interface under a frozen version, if your agent runs outside the JVM, or if you are not prepared to supply your own sandbox for ShellTools.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Gap This Fills Between Spring AI and a Working Agent
Spring AI gives you the model abstraction, the ChatClient, tool calling and advisors. What it does not give you is the tool layer that makes an agent useful: reading and editing files, running shell commands, searching a codebase, fetching a URL, keeping notes across sessions. Claude Code has that layer built in, but it is a closed product tied to Anthropic's CLI. This project reimplements those capabilities as Spring AI tools so a Java application can compose them.
The audience is narrow and specific. You are building an agent in Java, you have already chosen Spring AI as your model interface, and you want to spend your time on the agent's domain logic rather than on writing a grep wrapper and a file editor. The README frames the project as a demonstration of how to reverse-engineer Claude Code's features inside the Spring AI ecosystem, which is an honest description of what it is: a port of a known tool surface into a different runtime, not a new agent framework.
If you are writing Python agents or using LangChain, none of this applies to you. If you are on Spring AI and have been hand-rolling a ShellTools equivalent, this is the shortest path to a working tool set.
Module Layout: Core Tools, a Subagent SPI, and an A2A Bridge
The repository splits into four published modules plus examples. spring-ai-agent-utils-common holds the shared subagent SPI: interfaces and records named SubagentDefinition, SubagentResolver, SubagentExecutor and SubagentType. spring-ai-agent-utils is the core library containing the tools, advisors, skills and Claude subagents. spring-ai-agent-utils-a2a implements the A2A protocol so a subagent can live on a remote service rather than in the same JVM. spring-ai-agent-utils-bom is a bill of materials for version alignment.
That separation matters when you decide what to depend on. If you only want FileSystemTools and GrepTool, you take the core artifact. If you want to plug in your own subagent resolution logic, the SPI in the common module is the extension point, and the fact that it is a separate artifact suggests the maintainers expect third-party implementations. The A2A module is the interesting one architecturally: it means task delegation is not hardcoded to in-process agents.
The examples directory is unusually broad for a library this size, with separate demos for code-agent, ask-user-question, skills, subagent, subagent-a2a, todo, and three distinct memory demos (memory-tools-demo, memory-filesystem-tools-demo, memory-tools-advisor-demo). Three memory demos is a signal that the memory design changed and the older approaches were kept as reference rather than deleted.
How the Tools Actually Work: Sandboxed Files, Filtered Shell, Indexed Memory
FileSystemTools handles read, write and edit with what the README calls precise control, meaning edits are targeted rather than whole-file rewrites. GrepTool is described as a pure Java grep implementation, which is a deliberate constraint: it does not shell out to the system grep, so behaviour is identical on Linux, macOS and Windows, at the cost of not benefiting from ripgrep's speed on large trees. GlobTool does filename pattern matching in glob syntax. ShellTools executes commands with timeout control, background process management, and regex output filtering, which is the part that matters most in practice: an agent that dumps 40,000 lines of Maven output into the context window is useless, so the filtering is what keeps shell use viable.
AutoMemoryTools is the most opinionated piece. Agents write typed memory files into a sandboxed directory using four categories: user, feedback, project, reference. A MEMORY.md index file is the navigation surface. The README is explicit that the tools require a companion system prompt at classpath:/prompt/AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md, bundled in the jar, which instructs the agent on when and how to use them. That is a real coupling: the tools are not self-describing, and swapping in your own prompt will change behaviour in ways the tool descriptions alone do not cover.
AutoMemoryToolsAdvisor wraps the same capability as a ChatClient advisor, registering the tools and prompt automatically, deduplicating callbacks, and offering an optional memoryConsolidationTrigger that prompts the model to summarise and clean up memories on a schedule. The trigger is the part worth understanding before adopting: consolidation is model-driven, so it costs tokens and its output quality depends on the model you route it to.
Getting It Running: BOM, Dependency, and the Prompt You Must Not Forget
The README's quick start begins with the bill of materials. You declare org.springaicommunity:spring-ai-agent-utils-bom in dependencyManagement, then add the core artifact org.springaicommunity:spring-ai-agent-utils without a version. Java 17 or later is the stated requirement, per the badge in the README.
The README as supplied is truncated mid-XML, so the exact dependency block and the ChatClient wiring snippet are not available here. What can be confirmed from the material is the artifact coordinates, the BOM approach, the Java version floor, and the module names. For the tool registration API and the advisor configuration, you need the module README at spring-ai-agent-utils/README.md, which the project points to as the full API reference.
One setup detail is stated plainly and is easy to miss: AutoMemoryTools requires the companion system prompt from classpath:/prompt/AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md. If you register the tools manually rather than through AutoMemoryToolsAdvisor, you are responsible for supplying that prompt. The three memory demos exist precisely because there is more than one way to wire this, and the manual route is the one that breaks quietly.
ShellTools Is the Sharp Edge, and the Docs Are Thin on Containment
Every tool in this library that touches the host is a potential problem, but ShellTools is the one to think hardest about. The README describes timeout control, background process management and regex output filtering. It does not describe a permission model, an allowlist of commands, or a default sandbox.
There is a mitigation in the repository: the documentation table references spring-ai-agent-utils-docker-cli, described as a Docker ExecBackend that runs agent shell commands inside a sandbox container, located under exec-backends/. That is the right shape of solution, and it is also telling that it lives in a separate module rather than being the default. If you run ShellTools without that backend, the agent executes commands with the privileges of your application process.
The second limitation is version churn. Releases v0.10.0 in June, v0.11.0 in late August, and v0.12.0 four days later in the same month. Three releases in one month at a 0.x version number means the API is still being shaped. Pinning to a version and reading the release notes before upgrading is not optional here.
The third is the grep trade-off. A pure Java implementation will not match ripgrep on a large monorepo. For a code agent searching a big repository repeatedly, that difference compounds across a session.
Where It Sits Against LangChain4j and Hand-Rolled Tools
The obvious alternative is LangChain4j, which also targets Java and also ships tool abstractions, including file system and shell access. The difference in approach is the anchor point. LangChain4j is a framework with its own model client abstraction; you build against LangChain4j's interfaces and it talks to whichever provider you configure. Spring AI Agent Utils is not a framework at all. It is a set of tools written against Spring AI's tool-calling contract, which means it assumes you have already committed to Spring AI for model access.
That makes the choice largely determined before you reach this library. If your application is a Spring Boot service with Spring AI already wired, this drops in. If you are starting fresh and have no Spring commitment, LangChain4j gives you a broader framework with a comparable tool surface, and you would be choosing between ecosystems rather than between tool sets.
The second alternative is writing the tools yourself, which is what most teams do first. A FileSystemTools equivalent is perhaps a day of work. What you would not get for free is the accumulated detail: the regex output filtering on shell, the pure-Java grep for cross-platform consistency, the typed memory taxonomy with a MEMORY.md index, and the subagent SPI with an A2A implementation. Those are the parts that justify the dependency, and they are also the parts most likely to change between 0.x releases.
Maintenance Cost, Licence, and What the Version Number Implies
Apache-2.0 is permissive. You can use this in a commercial product, modify it, and redistribute it, provided you preserve the licence and notices. That is a statement about the licence text, not legal advice; if you are embedding it in a distributed product, have your own counsel review the NOTICE handling.
The maintenance cost is the version cadence. A 0.x library that shipped three releases in roughly two months of the supplied timeline will change method signatures. The BOM exists to make upgrades a single version bump, which helps, but it does not protect you from source-incompatible changes. Budget for reading release notes on each bump rather than assuming patch-level safety from the version string.
The subagent SPI in spring-ai-agent-utils-common is your hedge. If your delegation logic is written against SubagentResolver and SubagentExecutor rather than against the concrete Claude subagent implementation, a change in the core module is less likely to reach your code. That is the design intent behind splitting the SPI into its own artifact, and it is worth honouring in how you structure your own integration.
Editorial conclusion
Adopt it if you are already on Spring AI, need file, shell, grep, glob, web and task tools wired into a ChatClient, and can tolerate a 0.x API. Do not adopt it if you need a stable interface under a frozen version, if your agent runs outside the JVM, or if you are not prepared to supply your own sandbox for ShellTools. Before committing, verify the current AutoMemoryTools system prompt contract in the bundled classpath resource, confirm the SubagentResolver SPI in spring-ai-agent-utils-common matches your delegation model, and check whether the Docker ExecBackend is available in the version you pin.
Community notes