English | 简体中文

Java SDK for the Codex CLI: subprocess integration that drives the local codex agent (exec, interactive sessions, session resume / fork / archive, doctor, review) from Java.

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

codex-java-sdk lets Java applications run the Codex CLI agent (codex) as a local subprocess. It is a CLI wrapper, not a direct OpenAI API client — every call maps to a real codex command line invocation.

The SDK covers:

• Exec mode — codex exec <prompt> with model, sandbox, JSONL output, web search, output files, output schema, images, config overrides and ephemeral runs.
• Interactive sessions — codex [prompt] and full session lifecycle: resume / resumeLast / fork / archive / unarchive.
• Parsed models — CodexEvent (JSONL events), CodexSession, CodexDoctorReport.
• Utilities — doctor, review, login / logout, MCP management, update, features, shell completion.

What it is not:

• Not an OpenAI API client (no direct HTTP calls to the OpenAI API).
• Not a replacement for the codex binary — the CLI must be installed and runnable.

Typical scenarios:

Assumption: the capability statuses above reflect the current state of the 1.0.x branch; the module is under active development.

Version lines:

+------------------+   +------------------------------------------+
| Java application |   | codex-java-sdk                            |
|                  |-->|  CodexClient (facade)                    |
| prompt / options |   |    | CodexCli (command mapping)          |
|                  |   |    |   | CodexCliExecutor                |
|                  |   |    |   |   `codex` child process         |
|                  |   |    |   CodexCliResult                    |
+------------------+   |    | CodexEvent/CodexSession/DoctorReport|
                       +-------------------+----------------------+
                                           |
                                           v
                     +-------------------------------------------+
                     | Local `codex` CLI (exec, session, doctor, |
                     | review, login, ...)                       |
                     +-------------------------------------------+

Single-module Maven project (packaging: jar). No child modules.

Key packages:

The project is not yet published to Maven Central. Snapshots/releases are distributed through the Aliyun Maven repository and GitHub Releases.

Maven:

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

Gradle:

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

import io.github.easy4j.codex.CodexClient;
import io.github.easy4j.codex.CodexClientConfig;
import io.github.easy4j.codex.cli.CodexCliResult;

public class CodexDemo {

    public static void main(String[] args) {
        CodexClientConfig config = new CodexClientConfig();
        config.setLocalExecutable("codex");   // or an absolute path
        config.setLocalTimeoutSeconds(600);

        try (CodexClient client = new CodexClient(config)) {
            CodexCliResult result = client.exec("Write a Java hello world");
            System.out.println("exit=" + result.getExitCode());
            System.out.println(result.getStdout());
        }
    }
}

Expected result: codex exec "Write a Java hello world" runs locally; result.getExitCode() is 0 on success and result.getStdout() contains the agent's answer.

CodexClientConfig is a plain POJO (Spring @ConfigurationProperties-bindable). There is no configuration file of its own. Key fields:

try (CodexClient client = new CodexClient(config)) {
    // codex exec --json <prompt>, parsed into typed events
    List<CodexEvent> events = client.execAndParse("Fix the failing test");
    events.forEach(event -> System.out.println(event.getType() + " -> " + event.getMessage()));
}

try (CodexClient client = new CodexClient(config)) {
    client.exec("first task");                  // creates a persisted session
    client.resumeSession("session-id");         // resume an interactive session
    client.forkSession("session-id");           // fork into a new session
    client.archiveSession("session-id");        // archive a session
    client.execResume("session-id", "continue");// non-interactive resume
    client.doctorSummary();                     // environment diagnostics
}

./mvnw clean verify

• The build is configured with the JaCoCo Maven plugin (report + check goal with a 90% line-coverage rule bound to the verify phase; haltOnFailure=false).
• Assumption: the 1.0.x branch currently checks in no test sources under src/test; coverage thresholds are therefore enforced only when tests exist.
• No CI workflow files are present under .github/ in this worktree.

Maintenance policy: the 1.0.x line receives bug fixes and compatibility updates for the JDK 8 baseline. New features targeting newer JDKs land on the 2.0.x / 3.0.x lines. Releases are published to the Aliyun Maven repository and as GitHub Releases; the project is not yet published to Maven Central.

Contributions are welcome — please open issues or pull requests on GitHub.

Licensed under the Apache License, Version 2.0.