Typed JSON-RPC client for codex app-server: coroutine-driven session with response correlation and notification flows, high-level typed APIs, stdio/websocket transports, schema generation and testing tooling.
CoKit is a Kotlin Multiplatform client library for codex app-server.
The project provides typed Kotlin APIs over the app-server JSON-RPC protocol, with transport, protocol, RPC runtime, and high-level client concerns kept in separate modules.
CoKit is in early development. The current codebase includes:
CodexClient facade with typed descriptors for the currently modeled
app-server request APIs.codex app-server.The upstream app-server README documents a much broader protocol surface than CoKit currently models. See Protocol Compatibility for the current coverage snapshot and implementation roadmap.
Published artifacts use the io.github.vupoint.cokit group and include:
The repository also includes:
cokit-sample-cli: small JVM command-line sample that exercises the public
client and stdio transport APIs. This sample is not published as a Maven
Central library artifact.CoKit artifacts are published to Maven Central. Make sure your build resolves
dependencies from mavenCentral():
repositories {
mavenCentral()
}
Import the CoKit BOM once, then declare the CoKit modules you need without
repeating the version. Replace <version> with the CoKit release you want to
use:
dependencies {
implementation(platform("io.github.vupoint.cokit:cokit-bom:<version>"))
implementation("io.github.vupoint.cokit:cokit-client")
implementation("io.github.vupoint.cokit:cokit-transport-stdio")
}
For Groovy DSL builds, use the same coordinates:
repositories {
mavenCentral()
}
dependencies {
implementation platform("io.github.vupoint.cokit:cokit-bom:<version>")
implementation "io.github.vupoint.cokit:cokit-client"
implementation "io.github.vupoint.cokit:cokit-transport-stdio"
}
The BOM also aligns JVM target artifacts such as cokit-client-jvm and
cokit-client-api-jvm. Gradle builds should normally use the base module
coordinates above so Gradle module metadata can select the right variant.
Use cokit-client-api directly only when you need the public contracts and
models without the default client implementation.
Add cokit-testing only to test configurations:
dependencies {
testImplementation(platform("io.github.vupoint.cokit:cokit-bom:<version>"))
testImplementation("io.github.vupoint.cokit:cokit-testing")
}
val transport = StdioCodexTransport()
val client = CodexClients.connect(
CodexClientConnection(
transport = transport,
clientInfo = ClientInfo(
name = "cokit_sample",
title = "CoKit Sample",
version = "0.1.0",
),
scope = scope,
),
)
val thread = client.request(
CodexRpc.Thread.Start,
ThreadStartParams(cwd = CodexHostPath("/path/to/project")),
).thread
val turn = client.request(
CodexRpc.Turn.Start,
TurnStartParams(
threadId = thread.id,
input = listOf(TurnInput.Text("Summarize this repository")),
),
).turn
Show the included sample CLI help:
./gradlew :cokit-sample-cli:run --args="--help"
Start a real app-server thread, send the default message, and stream the
assistant response when codex is installed locally:
./gradlew :cokit-sample-cli:run
Override the default app-server host path or message when needed:
./gradlew :cokit-sample-cli:run --args='--cwd /path/to/project --message "Summarize this repository"'
The sample uses StdioCodexTransport defaults.
The command prints the created thread and turn ids, then streams assistant text
from typed CodexNotification.AgentMessageDelta events. If the turn completes
without assistant text, the sample reports that no assistant message was
produced; if the turn fails, it exits with the app-server error message.
CoKit follows the upstream app-server protocol documented in:
https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md
Generated app-server JSON Schema should be treated as the source of truth for wire shape changes.
Run:
./gradlew check
check includes unit tests, coverage verification, module-boundary validation,
public API exposure checks, Kotlin ABI validation, and primary docs/sample
alignment checks.
Run JVM unit tests only:
./gradlew test
Generate aggregate Kover coverage reports:
./gradlew coverage
The aggregate HTML report is written to build/reports/kover/html/index.html.
See Coverage for report paths and KMP coverage scope.
To run the real app-server integration smoke test on a machine with codex
installed:
COKIT_CODEX_INTEGRATION=1 ./gradlew :cokit-client:jvmTest
Before publishing a release candidate, follow the Release Readiness checklist.
cokit-bom: Maven BOM for aligning all published CoKit module and JVM target
artifact versions.cokit-protocol: JSON-RPC messages, protocol serializers, and schema
metadata. This module does not depend on client, runtime, or transport code.cokit-rpc: request correlation, notification routing, and server request
flow. This module depends on protocol types only.cokit-client-api: public client contracts, typed request descriptors,
notifications, server-request models, and shared option/value models.cokit-client: default CodexClient implementation and CodexClients
factory. The raw JSON-RPC session stays internal.cokit-transport-stdio: JVM stdio transport for the local Codex app-server.cokit-transport-websocket: experimental WebSocket transport placeholder.cokit-testing: fake transports and protocol test helpers for consumers and
CoKit module tests.Surfaced from shared tags and platforms — no rankings paid for.