Claudecode4j

ClaudeCode4J

Bring the agentic power of Claude Code to Java.

[English](README.md) • [中文](READMECN.md) • [فارسی](READMEFA.md) • [Español](README_ES.md)

[](https://github.com/sudoitir/claudecode4j/actions/workflows/ci.yml) [](https://sonarcloud.io/summary/newcode?id=sudoitirclaudecode4j) [](https://sonarcloud.io/summary/newcode?id=sudoitirclaudecode4j) [](https://sonarcloud.io/summary/newcode?id=sudoitirclaudecode4j)

---

A modern Java library for integrating with Claude Code CLI — Anthropic's agentic coding tool.

Table of Contents

• [Features](#features)
• [Requirements](#requirements)
• [Installation](#installation)
• [Maven BOM (Recommended)](#maven-bom-recommended)
• [Core Library (No Spring)](#core-library-no-spring)
• [Spring Boot Starter](#spring-boot-starter)
• [REST Adapter](#rest-adapter)
• [Kafka Adapter](#kafka-adapter)
• [WebSocket Adapter](#websocket-adapter)
• [MCP Server](#mcp-server)
• [Context Module (Token Optimization)](#context-module-token-optimization)
• [Quick Start](#quick-start)
• [Standalone Usage (No Spring)](#standalone-usage-no-spring)
• [Async Execution](#async-execution)
• [Streaming](#streaming)
• [Session Management](#session-management)
• [Spring Boot Integration](#spring-boot-integration)
• [Configuration](#configuration)
• [Auto-wired Usage](#auto-wired-usage)
• [Concurrency Limiting with AOP](#concurrency-limiting-with-aop)
• [REST API](#rest-api)
• [Endpoints](#endpoints)
• [Example Request](#example-request)
• [SSE Streaming](#sse-streaming)
• [OpenAI-Compatible API](#openai-compatible-api)
• [Configuration](#configuration-1)
• [Endpoints](#endpoints-1)
• [Example Request](#example-request-1)
• [Streaming Example](#streaming-example)
• [Response Format (Non-Streaming)](#response-format-non-streaming)
• [Streaming Format](#streaming-format)
• [Anthropic-Compatible API](#anthropic-compatible-api)
• [Configuration](#configuration-2)
• [Endpoints](#endpoints-2)
• [Example Request](#example-request-2)
• [Streaming Example](#streaming-example-1)
• [Response Format (Non-Streaming)](#response-format-non-streaming-1)
• [Streaming Format](#streaming-format-1)
• [Kafka Integration](#kafka-integration)
• [Configuration](#configuration-3)
• [Producer (Request Side)](#producer-request-side)
• [Consumer (Processing Side)](#consumer-processing-side)
• [Module Structure](#module-structure)
• [Exception Handling](#exception-handling)
• [Observability](#observability)
• [Health Check](#health-check)
• [Metrics (Micrometer)](#metrics-micrometer)
• [Security](#security)
• [Building from Source](#building-from-source)
• [Running Tests](#running-tests)
• [Test Profiles](#test-profiles)
• [Test Categories](#test-categories)
• [Contributing](#contributing)
• [License](#license)
• [Acknowledgments](#acknowledgments)

---

Features

• Pure Java API - Clean interfaces with sealed types and records
• Virtual Threads - Efficient concurrent execution using Project Loom
• Structured Concurrency - Safe parallel process management
• Spring Boot 4 Integration - Auto-configuration, health checks, and metrics
• REST API Adapter - HTTP endpoints with SSE streaming support
• Kafka Adapter - Request-reply pattern with correlation IDs
• WebSocket Terminal - Interactive sessions with human-in-the-loop support
• MCP Server - Expose Java methods as Claude tools via Model Context Protocol
• Smart Context - Token-aware context optimization using JTokkit
• Resilience - Built-in retry with exponential backoff
• JPMS Ready - Full Java Platform Module System support
• Null-Safe - JSpecify annotations throughout

Requirements

• Java 25+
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Maven 3.9+

Installation

Maven BOM (Recommended)

    
        
            io.github.sudoitir
            claudecode4j-bom
            2026.1.0
            pom
            import
        
    

Core Library (No Spring)

    io.github.sudoitir
    claudecode4j-core

Spring Boot Starter

    io.github.sudoitir
    claudecode4j-spring-boot-starter

REST Adapter

    io.github.sudoitir
    claudecode4j-rest-adapter

Kafka Adapter

    io.github.sudoitir
    claudecode4j-kafka-adapter

WebSocket Adapter

    io.github.sudoitir
    claudecode4j-websocket-adapter

MCP Server

    io.github.sudoitir
    claudecode4j-mcp-server

Context Module (Token Optimization)

    io.github.sudoitir
    claudecode4j-context

Quick Start

Standalone Usage (No Spring)

import ir.sudoit.claudecode4j.api.client.ClaudeClient;
import ir.sudoit.claudecode4j.api.model.request.Prompt;
import ir.sudoit.claudecode4j.core.client.DefaultClaudeClientFactory;

// Create client using SPI
ClaudeClient client = new DefaultClaudeClientFactory().create();

// Execute a prompt
Prompt prompt = Prompt.of("Explain what this code does");
ClaudeResponse response = client.execute(prompt);

// Handle response using pattern matching
switch (response) {
    case TextResponse text -> System.out.println(text.content());
    case StreamResponse stream -> stream.events().forEach(System.out::println);
    case ErrorResponse error -> System.err.println(error.message());
}

Async Execution

CompletableFuture future = client.executeAsync(prompt);
future.thenAccept(response -> {
    if (response instanceof TextResponse text) {
        System.out.println(text.content());
    }
});

Streaming

import ir.sudoit.claudecode4j.api.model.response.StreamEvent;
import java.util.stream.Stream;

Stream events = client.stream(prompt);
events.forEach(event -> {
    switch (event) {
        case StreamEvent.Text text -> System.out.print(text.content());
        case StreamEvent.Tool tool -> System.out.println("Tool: " + tool.name());
        case StreamEvent.Result result -> System.out.println("\nDone: " + result.success());
    }
});

Session Management

// Create a conversation session
ClaudeSession session = client.createSession();

// Continue conversation with context
ClaudeResponse response1 = session.send(Prompt.of("Create a Java class for User"));
ClaudeResponse response2 = session.send(Prompt.of("Add validation annotations"));

// Session maintains conversation history
session.close();

Spring Boot Integration

Configuration

claude:
  code:
    binary-path: /usr/local/bin/claude  # Optional: auto-detected
    concurrency-limit: 4                 # Max concurrent executions
    default-timeout: 5m                  # Execution timeout
    dangerously-skip-permissions: false  # Security flag
    health:
      enabled: true                      # Enable health indicator
      cache-duration: 30s                # Health check cache
    metrics:
      enabled: true                      # Enable Micrometer metrics

Auto-wired Usage

@Service
public class CodeAssistantService {

    private final ClaudeClient claudeClient;

    public CodeAssistantService(ClaudeClient claudeClient) {
        this.claudeClient = claudeClient;
    }

    public String analyzeCode(String code) {
        Prompt prompt = Prompt.builder()
            .text("Analyze this code for potential issues:\n" + code)
            .outputFormat(OutputFormat.TEXT)
            .build();

        ClaudeResponse response = claudeClient.execute(prompt);
        return switch (response) {
            case TextResponse text -> text.content();
            case ErrorResponse error -> "Error: " + error.message();
            default -> "Unexpected response";
        };
    }
}

Concurrency Limiting with AOP

@Service
public class RateLimitedService {

    private final ClaudeClient claudeClient;

    @ConcurrencyLimit(permits = 2)  // Max 2 concurrent calls to this method
    public ClaudeResponse processWithLimit(Prompt prompt) {
        return claudeClient.execute(prompt);
    }
}

REST API

Enable the REST adapter to expose Claude functionality via HTTP:

claude:
  code:
    rest:
      enabled: true
      base-path: /api/claude

Endpoints

| Method | Path | Description | |--------|----------------------------|-------------------------------| | POST | /api/claude/prompt | Execute prompt synchronously | | POST | /api/claude/prompt/async | Execute prompt asynchronously | | POST | /api/claude/stream | Stream response via SSE | | GET | /api/claude/health | Health check |

Example Request

curl -X POST http://localhost:8080/api/claude/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Write a hello world in Rust",
    "outputFormat": "TEXT",
    "timeout": "PT30S"
  }'

SSE Streaming

curl -N http://localhost:8080/api/claude/stream \
  -H "Content-Type: application/json" \
  -d '{"text": "Explain microservices architecture"}'

OpenAI-Compatible API

The REST adapter includes an OpenAI-compatible /v1/chat/completions endpoint, allowing tools and applications designed for OpenAI's API to work with Claude Code CLI.

Configuration

claude:
  code:
    rest:
      openai:
        enabled: true                    # Enable OpenAI-compatible endpoint (default: true)
        base-path: /v1                   # Base path for OpenAI endpoints (default: /v1)

Endpoints

| Method | Path | Description | |--------|------------------------|----------------------------------------| | POST | /v1/chat/completions | OpenAI-compatible chat completions API |

Example Request

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a hello world in Rust"}
    ],
    "max_tokens": 1000,
    "temperature": 0.7,
    "stream": false
  }'

Streaming Example

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ],
    "stream": true
  }'

Response Format (Non-Streaming)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "claude-3-5-sonnet-20241022",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, World! in Rust:\n\nfn main() {\n    println!(\"Hello, World!\");\n}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 30,
    "total_tokens": 50
  }
}

Streaming Format

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"claude-3-5-sonnet-20241022","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"claude-3-5-sonnet-20241022","choices":[{"index":0,"delta":{"content": " World!"},"finish_reason":null}]}

data: [DONE]

Anthropic-Compatible API

The REST adapter also includes an Anthropic-compatible /v1/messages endpoint, following Anthropic's Messages API specification.

Configuration

claude:
  code:
    rest:
      anthropic:
        enabled: true                    # Enable Anthropic-compatible endpoint (default: true)
        base-path: /v1                   # Base path for Anthropic endpoints (default: /v1)

Endpoints

| Method | Path | Description | |--------|----------------|-----------------------------------| | POST | /v1/messages | Anthropic-compatible Messages API |

Example Request

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: not-required" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1000,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Write a hello world in Rust"}
    ],
    "stream": false
  }'

Streaming Example

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1000,
    "messages": [
      {"role": "user", "content": "Explain reactive programming"}
    ],
    "stream": true
  }'

Response Format (Non-Streaming)

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here is a hello world in Rust:\n\nfn main() {\n    println!(\"Hello, World!\");\n}"
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 25
  }
}

Streaming Format

event: message_start
data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[]}}

event: content_block_start
data: {"type":"content_block_start","index":0}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Here is"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":25}}

event: message_stop
data: {"type":"message_stop"}

Kafka Integration

Enable request-reply messaging over Kafka:

claude:
  code:
    kafka:
      enabled: true
      request-topic: claude-requests
      reply-topic: claude-replies
      group-id: claude-processor
      reply-timeout: 5m

Producer (Request Side)

@Service
public class KafkaPromptService {

    private final ClaudeKafkaProducer producer;

    public CompletableFuture sendPrompt(String text) {
        return producer.sendRequest(text);
    }
}

Consumer (Processing Side)

The ClaudeKafkaListener automatically:

1. Consumes messages from request-topic
2. Executes prompts via ClaudeClient
3. Sends responses to reply-topic with correlation ID

Module Structure

claudecode4j/
├── claudecode4j-bom/                 # Bill of Materials
├── claudecode4j-api/                 # Interfaces & DTOs
│   ├── client/                       # ClaudeClient, ClaudeSession
│   ├── model/                        # Prompt, Response records
│   ├── exception/                    # Sealed exception hierarchy
│   └── spi/                          # Extension points
├── claudecode4j-core/                # Pure Java implementation
│   ├── client/                       # DefaultClaudeClient
│   ├── process/                      # VirtualThreadExecutor
│   ├── parser/                       # StreamJsonParser
│   └── resolver/                     # Binary resolvers
├── claudecode4j-context/             # Token-aware context optimization
│   ├── spi/                          # TokenCounter, ContextOptimizer
│   ├── model/                        # ContextBudget, ModelTokenLimits
│   ├── tokenizer/                    # JTokkit implementation
│   └── optimizer/                    # DefaultContextOptimizer
├── claudecode4j-spring-boot-starter/ # Spring Boot integration
│   ├── autoconfigure/                # Auto-configuration
│   ├── properties/                   # ConfigurationProperties
│   ├── health/                       # HealthIndicator
│   ├── metrics/                      # Micrometer metrics
│   └── resilience/

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sudoitir](https://github.com/sudoitir)
- **Source:** [sudoitir/claudecode4j](https://github.com/sudoitir/claudecode4j)
- **License:** MIT

Install and usage instructions live in the source repository linked above.