claudecode4j: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ClaudeCode4J is a Java library for integrating with Claude Code CLI. It wraps the CLI tool and provides a clean Java API for executing prompts, streaming responses, and managing sessions.

Build Commands

# Build entire project
mvn clean install

# Build without tests
mvn clean install -DskipTests

# Run unit tests only (excludes integration and E2E tests)
mvn test

# Run a single test class
mvn test -Dtest=ClaudeRestIntegrationTest

# Run a single test method
mvn test -Dtest=ClaudeRestIntegrationTest#shouldExecutePromptAndReturnResponse

# Run tests for a specific module
mvn test -pl claudecode4j-core

# Run integration tests (requires Docker for Testcontainers)
mvn verify -Pintegration

# Run all tests including E2E (requires Claude CLI installed and authenticated)
mvn verify -Pall

# Format code (Spotless with Palantir Java Format)
mvn spotless:apply

# Check formatting
mvn spotless:check

Architecture

Module Structure

• claudecode4j-bom: Bill of Materials for version management
• claudecode4j-api: Interfaces, DTOs, and SPIs (no implementation)
• claudecode4j-core: Pure Java implementation (no Spring dependency)
• claudecode4j-spring-boot-starter: Spring Boot 4 auto-configuration
• claudecode4j-rest-adapter: REST/SSE endpoints with OpenAI and Anthropic API compatibility
• claudecode4j-kafka-adapter: Kafka request-reply messaging
• claudecode4j-websocket-adapter: WebSocket terminal for interactive sessions
• claudecode4j-mcp-server: MCP Server support for exposing Java methods as Claude tools
• claudecode4j-context: Token-aware context optimization using JTokkit

Key Design Patterns

Sealed Types: ClaudeResponse and ClaudeException use sealed interfaces/classes with pattern matching:

switch (response) {
    case TextResponse text -> ...
    case StreamResponse stream -> ...
    case ErrorResponse error -> ...
}