A loop-driven interactive coding agent CLI for Java developers. Built on Spring AI with an embedded agent loop, modern terminal UI, and domain skills.

Loopy is the entry point for knowledge-directed execution — the idea that curated domain knowledge + structured execution contribute more to agent quality than model choice alone.

• Spring Boot scaffolding — create, analyze, extend, and modify Spring Boot projects with /boot-new, /boot-add, /starters, and /boot-modify. No calls to start.spring.io — all knowledge is bundled.
• Skills — domain knowledge that makes agents smarter. Discover, install, and create skills from a curated catalog of 23+ skills. Skills follow the agentskills.io spec and work in any agentic CLI
• Multi-provider — Anthropic (default), OpenAI, Google Gemini. Switch with --provider
• Three modes — interactive TUI, single-shot print (-p), REPL (--repl)
• Cost visibility — per-turn token usage and estimated cost
• Context compaction — automatic summarization for long sessions
• CLAUDE.md auto-injection — project-specific instructions, same convention as Claude Code
• Forge agent — scaffold agent experiment projects from YAML briefs

• Getting Started — installation, API key setup, first session
• CLI Reference — all commands, flags, and modes
• Spring Boot Scaffolding — /boot-new, /starters, /boot-add, /boot-modify
• Subagents — built-in subagents, custom subagents, multi-model routing
• Configuration — environment variables, model selection, custom endpoints
• Architecture — four-layer design, data flow, quality guardrails
• Forge Agent — scaffolding experiment projects with /forge-agent

• Java 21+ — check with java -version. Install via SDKMAN: sdk install java 21.0.9-librca
• API key for at least one provider:

export ANTHROPIC_API_KEY=sk-ant-...

Add the export to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

Grab the executable jar from the latest release and run it. No API key is needed to check that it works:

curl -LO https://github.com/markpollack/loopy/releases/latest/download/loopy-0.5.0-exec.jar
java -jar loopy-0.5.0-exec.jar --version
java -jar loopy-0.5.0-exec.jar

The -exec suffix matters: that is the self-contained executable image. See Which jar do I want? below.

The launcher finds the jar, checks for Java, and adds the JVM flags Loopy wants:

curl -LO https://raw.githubusercontent.com/markpollack/loopy/main/loopy
chmod +x loopy
./loopy

Keep loopy and loopy-<version>-exec.jar in the same directory, or point LOOPY_JAR at the jar. Windows users want loopy.bat from the same location.

git clone https://github.com/markpollack/loopy.git
cd loopy
./mvnw package
./loopy                      # resolves target/loopy-<version>-exec.jar automatically

jbang loopy@markpollack/loopy

Loopy's slash commands, tools, and agent loop are usable from Java. This is the plain library jar, not the executable image:

<dependency>
    <groupId>io.github.markpollack</groupId>
    <artifactId>loopy</artifactId>
    <version>0.5.0</version>
</dependency>

Every release publishes two artifacts, and picking the wrong one is the most common first-run problem:

The executable jar is not on Maven Central — it is a GitHub Release asset. The library jar is not runnable with java -jar.

Releases before 0.5.0 published a single Spring Boot fat jar under the plain coordinate. It was never resolvable as a dependency, and no release before 0.5.0 had a downloadable asset attached at all.

Loopy supports three modes for different workflows:

Full terminal UI with chat history, async agent calls, and spinner animation:

loopy

Type messages to chat with the agent. Use slash commands (see below) for built-in operations. The TUI uses an Elm Architecture via tui4j.

Run a single task and exit — useful for scripting and CI:

loopy -p "refactor this class to use the builder pattern"

Output goes to stdout, status to stderr. Exit code 0 on success, 1 on failure.

Simple line-by-line prompt for testing and quick tasks:

loopy --repl

In TUI and REPL modes, lines starting with / are intercepted before reaching the agent — no LLM tokens wasted.

Skills are curated knowledge packages that make agents smarter. They follow the agentskills.io specification and work in 40+ agentic CLIs — not just Loopy.

loopy --repl
> /skills                          # List installed and discovered skills
> /skills search testing           # Search the curated catalog
> /skills info systematic-debugging  # Skill details + install instructions
> /skills add systematic-debugging   # Install to ~/.claude/skills/
> /skills remove systematic-debugging  # Uninstall

Loopy discovers skills from three sources:

Progressive disclosure — the agent sees skill names and descriptions, and loads full content only when relevant to the task. No tokens wasted on unused skills.

Curated catalog — 23 skills from 8 publishers covering testing, debugging, security, code review, architecture, and more. Run /skills search to browse.

Place a SKILL.md file in .claude/skills/<name>/ (project) or ~/.claude/skills/<name>/ (global):

---
name: my-team-conventions
description: Coding conventions for my team's Spring Boot codebase
---

# Instructions

When working on this codebase:
- Use constructor injection, never field injection
- All REST endpoints return ProblemDetail for errors
- Tests use @WebMvcTest with MockMvc

Loopy includes a full Spring Boot project lifecycle — create, discover capabilities, extend, and modify — with no dependency on start.spring.io or the Spring Initializr library. Knowledge is bundled; execution is deterministic.

# Create a new project
/boot-new --template spring-boot-rest --name products-api --group com.acme

# Discover what capabilities are available for your project
/starters suggest

# Bootstrap domain capabilities into an existing project
/boot-add spring-ai-starter-data-jpa

# Modify project structure
/boot-modify set java version 21
/boot-modify add native image support
/boot-modify add multi-arch CI
/boot-modify I need health check endpoints

/boot-modify understands natural language. For common operations it uses no AI at all (keyword shortcuts). For natural-language variations it uses a single lightweight classification call, then executes deterministically. The AI never writes POM XML — all POM changes go through Maven's own object model.

See Spring Boot Scaffolding for the full reference.

Loopy automatically reads CLAUDE.md from the working directory and appends it to the agent's system prompt. This gives the agent project-specific context without any CLI flags — the same convention used by Claude Code.

Every response shows token usage and estimated cost:

tokens: 1234/567 | cost: $0.0089

Long sessions can exceed the model's context window. Loopy automatically summarizes older messages when estimated tokens exceed 50% of the model limit, using a cheap model from the same provider (e.g., Haiku for Anthropic, gpt-4o-mini for OpenAI, gemini-2.5-flash-lite for Gemini). This reuses the same API credentials via a per-request model override.

The embedded agent has access to:

If no API key is set for the selected provider, the TUI launches in echo mode — useful for testing the UI and slash commands without consuming API tokens.

Embed Loopy's agent in other Java projects via LoopyAgent:

LoopyAgent agent = LoopyAgent.builder()
    .model("claude-haiku-4-5-20251001")
    .workingDirectory(workspace)
    .systemPrompt("You are a Spring Boot expert.")
    .maxTurns(80)
    .build();

// Single task
LoopyResult result = agent.run("add input validation to UserController");

// Multi-step with session memory (context preserved across calls)
LoopyResult plan = agent.run("plan the refactoring of the service layer");
LoopyResult act = agent.run("now execute the plan");

Note: The programmatic API defaults to claude-sonnet-4-6 via Anthropic only. CLI mode defaults are set per-provider in application.yml (Anthropic: claude-sonnet-4-20250514, OpenAI: gpt-4o, Gemini: gemini-2.5-flash).

Loopy supports Anthropic-compatible API endpoints (vLLM, LM Studio, etc.) via the .baseUrl() builder method. HTTP/1.1 fallback is applied automatically for custom endpoints:

LoopyAgent agent = LoopyAgent.builder()
    .baseUrl("http://localhost:1234/v1")
    .apiKey("lm-studio")
    .model("local-model")
    .workingDirectory(workspace)
    .build();

Single Maven module with five layers:

io.github.markpollack.loopy
├── agent/    MiniAgent loop, AgentLoopAdvisor, BashTool, SkillsTool, observability
├── tui/      ChatScreen (Elm Architecture via tui4j), ChatEntry
├── command/  SlashCommand interface, registry, /help, /clear, /quit, /skills
├── boot/     /boot-new, /starters, /boot-add, /boot-modify, PomMutator, SAE analyzer
└── forge/    ExperimentBrief, TemplateCloner, TemplateCustomizer, /forge-agent

• Agent layer — MiniAgent is an embedded agent loop (copied from agent-harness, evolving independently). It runs a think-act-observe loop with tool calling. SkillsTool provides progressive skill discovery.
• TUI layer — Elm Architecture UI via tui4j. Agent calls run on a background thread; a spinner animates while waiting; Enter is gated to prevent overlapping calls.
• Command layer — Slash commands are intercepted in ChatScreen.submitInput() before reaching the agent. New commands implement the SlashCommand interface and register in SlashCommandRegistry.
• Boot layer — Spring Boot scaffolding: four commands, bundled templates, BootProjectAnalyzer (SAE), PomMutator (Maven object model), RecipeCatalog (deterministic operations), RecipeClassifier (lightweight AI classification).
• Forge layer — /forge-agent scaffolds agent experiment projects from YAML briefs: clone template, rename packages, update POM, generate config and README.

Business Source License 1.1 — free for non-production and limited production use. Converts to Apache 2.0 on the Change Date.