Getting Started with Loopy

Prerequisites

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

Provider	Environment Variable	Get a key
Anthropic (default)	`ANTHROPIC_API_KEY`	console.anthropic.com
OpenAI	`OPENAI_API_KEY`	platform.openai.com
Google Gemini	`GOOGLE_API_KEY`	aistudio.google.com

export ANTHROPIC_API_KEY=sk-ant-...

Install

Each release publishes two jars. The one you run is loopy-<version>-exec.jar — the self-contained executable image, attached to the GitHub Release. The plain loopy-<version>.jar on Maven Central is a library jar for embedding Loopy in Java code and is not runnable with java -jar.

Download the executable jar

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

Check the download

java -jar loopy-0.5.0-exec.jar --version

--version and --help work without an API key, so you can confirm the download before setting up a provider.

Run it

java -jar loopy-0.5.0-exec.jar

The TUI launches with a chat interface. Type a message and press Enter.

Launcher script

The launcher finds the jar, checks for Java, and applies the JVM flags Loopy expects:

curl -LO https://github.com/markpollack/loopy/releases/latest/download/loopy-0.5.0-exec.jar
curl -LO https://raw.githubusercontent.com/markpollack/loopy/main/loopy
chmod +x loopy
./loopy

Keep the script beside the jar, or set LOOPY_JAR to the jar’s path. Windows users want loopy.bat from the same location.

JBang

jbang loopy@markpollack/loopy

Requires Loopy 0.5.0 or newer.

Build from source

git clone https://github.com/markpollack/loopy.git
cd loopy
./mvnw package
./loopy

Embed the library

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

Your First Session

Loopy starts in interactive TUI mode by default — a terminal chat interface with real-time agent feedback and a spinner while the agent thinks. Try giving it a coding task:

> Add input validation to the User class — name must be non-blank, email must match RFC 5322

The agent reads your codebase (via CLAUDE.md if present), plans the change, edits files, and verifies the result. You see token usage and estimated cost after each response:

tokens: 1234/567 | cost: $0.0089

Three Execution Modes

Mode	Command	Use case
TUI (default)	`loopy`	Interactive development — chat, iterate, explore
Print	`loopy -p "your task"`	Scripting and CI — single task, stdout output
REPL	`loopy --repl`	Quick tasks — readline loop, no TUI overhead

Slash Commands

Lines starting with / are intercepted before reaching the agent — no LLM tokens consumed.

Command	What it does
`/help`	List all commands
`/skills`	Discover, search, install domain skills
`/boot-new`	Scaffold a new Spring Boot project
`/starters`	Discover Agent Starters for your project
`/boot-add`	Add capabilities to an existing project
`/boot-modify`	Structural changes (Java version, CI, native image)
`/btw <question>`	Side question without polluting session context
`/session save`	Save current session for later
`/clear`	Reset conversation memory

Add Project Context

Create a CLAUDE.md file in your project root. Loopy reads it automatically and appends it to the agent’s system prompt — same convention as Claude Code.

# My Project

- Spring Boot 3.4 with Java 21
- Use constructor injection, never field injection
- Tests use @WebMvcTest with MockMvc
- API returns ProblemDetail for errors (RFC 9457)

No CLI flags needed. The agent sees your conventions on every turn.

What’s Next

Extending Loopy

Custom skills, subagents, tool profiles, and the programmatic API

CLI Reference

All flags, options, and configuration

Projects

AgentWorks

Supporting Projects

Migration

Getting Started with Loopy

Prerequisites

Install

Launcher script

JBang

Build from source

Embed the library

Your First Session

Three Execution Modes

Slash Commands

Add Project Context

What’s Next

Extending Loopy

CLI Reference

​Prerequisites

​Install

​Launcher script

​JBang

​Build from source

​Embed the library

​Your First Session

​Three Execution Modes

​Slash Commands

​Add Project Context

​What’s Next

Extending Loopy

CLI Reference

Prerequisites

Install

Launcher script

JBang

Build from source

Embed the library

Your First Session

Three Execution Modes

Slash Commands

Add Project Context

What’s Next