English | 简体中文

Pure Java SDK (no Spring) for the OpenCode Server: HTTP REST API, SSE event stream and local CLI 简体中文

Current branch: feature/2.0.x Version: 2.0.x.x.20260630-SNAPSHOT JDK baseline: 8 Project status: stable (1.0.x line). Not yet published to Maven Central; artifacts are distributed via the Aliyun Maven repository and GitHub Releases.

• 1. Project Overview
• 2. Features & Status
• 3. Requirements & Compatibility
• 4. Architecture & Modules
• 5. Installation
• 6. Quick Start
• 7. Configuration
• 8. Core Usage
• 9. Testing & Build
• 10. Versioning & Branches
• 11. Contributing & License

opencode-java-sdk is a pure Java library (no Spring) for interacting with the OpenCode Server through three independent, non-degrading channels:

• HTTP Server API — session management, prompt sending, agent queries, config/project/provider/file management over the REST API exposed by opencode serve;
• SSE event stream — consuming GET /event real-time events;
• Local CLI — wrapping opencode run, opencode session and many more subcommands.

The current SDK adapts opencode v1.17.18 CLI + Server HTTP API.

• Not the OpenCode Server itself.
• No Spring dependency; Spring Boot applications should use the companion opencode-spring-boot-starter.

Version-line matrix:

[ Java Application ]
        |
        | opencode-java-sdk
        v
+------------------------------------------+
| OpenCodeClient (facade)                   |
|  HTTP   /session, /agent, /config,        |
|         /project, /provider, /file,       |
|         /find, /command, /skill, /mcp ... |
|  SSE    GET /event (subscribe, typed      |
|         EventHandler callbacks)           |
|  CLI    opencode run / session / serve /  |
|         auth / mcp / debug ...            |
+------------------------------------------+
        |
        v
[ OpenCode Server (opencode serve) ]

Single-module library (packaging jar). Package layout:

Maven:

<dependency>
    <groupId>io.github.easy4j</groupId>
    <artifactId>opencode-java-sdk</artifactId>
    <version>2.0.x.x.20260630-SNAPSHOT</version>
</dependency>

Gradle:

implementation 'io.github.easy4j:opencode-java-sdk:2.0.x.x.20260630-SNAPSHOT'

Snapshot builds require an enabled snapshot repository (Aliyun Maven snapshot repository per distributionManagement in pom.xml).

OpenCodeClientConfig config = new OpenCodeClientConfig();
config.getHttp().setServerUrl("http://localhost:4096");
config.getHttp().setPassword("your-password");   // matches OPENCODE_SERVER_PASSWORD

OpenCodeClient client = new OpenCodeClient(config);

// Health check
HealthStatus health = client.health();
System.out.println("version: " + health.getVersion());

// Create a session and chat
Session session = client.createSession("my-task");
PromptResult result = client.chatCompletion(session.getId(),
        "Explain how closures work in JavaScript");
System.out.println(result.getTextContent());

// Async prompt (no waiting)
client.chatCompletionAsync(session.getId(), "Write a hello world in Python");

// List agents
List<Agent> agents = client.listAgents();

client.close();

Expected result: with a running opencode serve on port 4096 (started with OPENCODE_SERVER_PASSWORD=your-password opencode serve), health() returns the server version, the chat call returns the model's text content, and the async prompt is accepted without blocking.

Configuration is object-based. OpenCodeClientConfig aggregates http (an OpenCodeHttpClientConfig) and cli (an OpenCodeCliConfig).

OpenCodeHttpClientConfig properties:

OpenCodeCliConfig properties:

client.onSessionEvent(sessionId, new EventHandler() {
    @Override public void onTextDelta(String delta, Event event) {
        System.out.print(delta);
    }
    @Override public void onToolCall(String name, Map<String, Object> input, Event event) {
        System.out.println("\ntool call: " + name);
    }
    @Override public void onSessionIdle(String sessionId, Event event) {
        System.out.println("\n[done]");
    }
});

OpenCodeCli cli = client.cli();

// Non-interactive mode
OpenCodeCliResult result = cli.run("Explain async/await in JavaScript");
System.out.println(result.getStdout());

cli.run("Hello", "plan", "anthropic/claude-sonnet-4-5");  // agent + model
cli.sessionList();
cli.serve(4096, "127.0.0.1");                             // opencode serve --port 4096 --hostname 127.0.0.1
cli.upgrade("v1.18.0", "npm");

All cli*() methods also have facade equivalents on OpenCodeClient (e.g. cliServe, cliModels).

mvn clean verify

• The HTTP client is tested against MockWebServer (src/test/java/io/github/easy4j/opencode/api/OpenCodeHttpClientTest.java).
• JaCoCo runs prepare-agent, report and check on the verify phase with a 90% line-coverage rule (haltOnFailure=false).
• Release packaging (mvn -Prelease deploy) attaches sources and javadoc jars, GPG-signs artifacts and is wired for Sonatype Central Publishing; plain mvn deploy routes SNAPSHOT/release artifacts to the Aliyun Maven repository per distributionManagement.

Run mvn clean verify before opening a pull request and describe compatibility, testing, documentation and migration impact. This project is licensed under the Apache License 2.0.